Accelint Ac To Playwright

import type { ConsoleMessage, Page, TestInfo } from "@playwright/test";

export async function setupConsoleTracking(args: {
  page: Page;
  testInfo: TestInfo;
}) {
  const { page, testInfo } = args;
  const consoleMessages: Array<{ type: string; text: string; stepIndex: number; timestamp: string; location: { url: string; lineNumber?: number; columnNumber?: number } }> = [];
  let currentStep = 0;

  page.on('console', (msg: ConsoleMessage) => {
    consoleMessages.push({
      type: msg.type(),
      text: msg.text(),
      stepIndex: currentStep,
      timestamp: new Date().toISOString(),
      location: msg.location()
    });
  });

  return {
    setStep: (step: number) => { currentStep = step; },
    attachMessages: async () => {
      if (consoleMessages.length > 0) {
        await testInfo.attach('console-messages', {
          contentType: 'application/json',
          body: Buffer.from(JSON.stringify(consoleMessages, null, 2), 'utf8')
        });
      }
    }
  };
}

import type { Page, TestInfo } from "@playwright/test";

export async function attachFailureArtifacts(args: {
  page: Page;
  testInfo: TestInfo;
  stepIndex: number;
  action: string;
  testId?: string;
}) {
  const { page, testInfo, stepIndex, action, testId } = args;
  if (!testInfo) return;
  const payload = {
    url: page.url(),
    stepIndex,
    action,
    testId,
  };
  await testInfo.attach("step failure", {
    contentType: "application/json",
    body: Buffer.from(JSON.stringify(payload, null, 2), "utf8"),
  });
  try {
    const screenshot = await page.screenshot({ fullPage: true });
    await testInfo.attach("step screenshot", {
      contentType: "image/png",
      body: screenshot,
    });
  } catch {
    // ignore screenshot issues
  }
  try {
    const video = page.video?.();
    if (video) {
      const path = await video.path();
      await testInfo.attach("step video", {
        contentType: "video/webm",
        path,
      });
    }
  } catch {
    // ignore video issues
  }
}

import { defineConfig, devices } from '@playwright/test';

/**
 * Read environment variables from file.
 * https://github.com/motdotla/dotenv
 */
// import dotenv from 'dotenv';
// import path from 'path';
// dotenv.config({ path: path.resolve(__dirname, '.env') });

/**
 * See https://playwright.dev/docs/test-configuration.
 */
export default defineConfig({
  testDir: './tests',
  testMatch: /.*\.spec\.ts/,
  /* Run tests in files in parallel */
  fullyParallel: true,
  /* Fail the build on CI if you accidentally left test.only in the source code. */
  forbidOnly: !!process.env.CI,
  /* Retry on CI only */
  retries: process.env.CI ? 2 : 0,
  /* Opt out of parallel tests on CI. */
  workers: process.env.CI ? 1 : undefined,
  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
  reporter: 'html',
  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
  use: {
    /* Base URL to use in actions like `await page.goto('')`. */
    baseURL: 'http://localhost:3000',

    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
    trace: 'on-first-retry',
  },

  /* Configure projects for major browsers */
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },

    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },

    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },

    /* Test against mobile viewports. */
    // {
    //   name: 'Mobile Chrome',
    //   use: { ...devices['Pixel 5'] },
    // },
    // {
    //   name: 'Mobile Safari',
    //   use: { ...devices['iPhone 12'] },
    // },

    /* Test against branded browsers. */
    // {
    //   name: 'Microsoft Edge',
    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
    // },
    // {
    //   name: 'Google Chrome',
    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
    // },
  ]

});

{
	"name": "accelint-ac-to-playwright",
	"version": "1.0.0",
	"private": true,
	"description": "Convert acceptance criteria into JSON test plans and Playwright spec files",
	"license": "UNLICENSED",
	"bin": {
		"generate-tests": "dist/scripts/cli/generate-tests.js",
		"validate-plan": "dist/scripts/cli/validate-plan.js",
		"append-json-summary-entry": "dist/scripts/cli/append-json-summary-entry.js",
		"create-markdown-summary": "dist/scripts/cli/create-markdown-summary.js"
	},
	"scripts": {
		"build": "tsc",
		"test": "vitest --coverage"
	},
	"devDependencies": {
		"@types/node": "^25.0.3",
		"@vitest/coverage-istanbul": "^4.0.18",
		"typescript": "^5.9.3",
		"vitest": "^4.0.18"
	},
	"dependencies": {
		"zod": "^4.2.1"
	},
	"engines": {
		"node": ">=25.3.0"
	}
}

/**
 * Controlled vocabulary for target area keywords.
 * Last item in array is the fallback when no specific area matches.
 */
export const areaKeywords = [
  "nav",
  "header",
  "footer",
  "form",
  "drawer",
  "card",
  "toast",
  "modal",
  "table",
  "page",
  "area",
] as const;

/**
 * Controlled vocabulary for target component keywords.
 * Last item in array is the fallback when no specific component matches.
 */
export const componentKeywords = [
  "button",
  "link",
  "input",
  "dropdown",
  "checkbox",
  "radio",
  "text",
  "div",
  "component",
] as const;

#!/usr/bin/env node

import fs from "node:fs";
import path from "node:path";
import { z } from "zod";
import { type TestSuite, testSuiteSchema } from "../plan-schema";
import { handleCliCommonErrors } from "../utils/cli";

// Explicit types matching actual usage patterns (instead of Pick<typeof fs, ...>)
// This allows TypeScript to properly type-check mocks without overload ambiguity
type FsSubset = {
  existsSync: (path: fs.PathLike) => boolean;
  readFileSync: (
    path: fs.PathOrFileDescriptor,
    encoding: BufferEncoding,
  ) => string;
  mkdirSync: (
    path: fs.PathLike,
    options?: fs.MakeDirectoryOptions,
  ) => string | undefined;
  writeFileSync: (
    path: fs.PathOrFileDescriptor,
    data: string | NodeJS.ArrayBufferView,
    options?: fs.WriteFileOptions,
  ) => void;
};

type PathSubset = {
  dirname: (path: string) => string;
};

export type CliRuntime = {
  fs: FsSubset;
  path: PathSubset;
  log: (...args: unknown[]) => void;
  error: (...args: unknown[]) => void;
};

const defaultRuntime: CliRuntime = {
  fs,
  path,
  log: console.log,
  error: console.error,
};

type SummaryEntry = {
  input: string;
  outputs: {
    plan: string;
    test: string;
  };
  tests: Array<{
    name: string;
    requiredTestHooks: string[];
  }>;
};

type SummaryFile = {
  runDate: string;
  entries: SummaryEntry[];
};

type ParsedArgs = {
  summaryJson?: string;
  input?: string;
  plan?: string;
  test?: string;
  runDate?: string;
  help: boolean;
  errors: string[];
};

// CLI entrypoint
if (require.main === module) {
  const code = run(process.argv);
  process.exit(code);
}

export function run(
  argv: string[],
  runtime: CliRuntime = defaultRuntime,
): number {
  // Parse args
  const parsed = parseArgs(argv.slice(2));
  const exitCode = handleCliCommonErrors({
    parsed,
    runtime,
    printUsage,
    required: {
      summaryJson: "Error: Missing required option: --summary-json <path>",
      input: "Error: Missing required option: --input <ac-file>",
      plan: "Error: Missing required option: --plan <plan.json>",
      test: "Error: Missing required option: --test <spec.ts>",
    },
  });
  if (exitCode >= 0) return exitCode;
  if (!parsed.summaryJson || !parsed.input || !parsed.plan || !parsed.test) {
    return 1;
  }

  // Reads inputs
  const summaryPath = parsed.summaryJson;
  const inputPath = parsed.input;
  const planPath = parsed.plan;
  const testPath = parsed.test;

  // Read the raw plan
  let planRaw: string;
  try {
    planRaw = runtime.fs.readFileSync(planPath, "utf8");
  } catch {
    runtime.error(`Error: Unable to read plan file: ${planPath}`);
    return 1;
  }

  // Parse the raw plan
  let parsedPlan: unknown;
  try {
    parsedPlan = JSON.parse(planRaw);
  } catch {
    runtime.error(`Error: Invalid JSON in plan file: ${planPath}`);
    return 1;
  }

  // Invalid plan per the schema
  const planValidation = testSuiteSchema.safeParse(parsedPlan);
  if (!planValidation.success) {
    runtime.error(`Error: Invalid test suite in plan file: ${planPath}`);
    runtime.error(z.prettifyError(planValidation.error));
    return 1;
  }

  // Build summary entry
  const plan = planValidation.data;
  const entry: SummaryEntry = {
    input: inputPath,
    outputs: {
      plan: planPath,
      test: testPath,
    },
    tests: buildTestSummaries(plan),
  };

  // Grab the existing summary file if present or start a new one
  let summary: SummaryFile;
  if (runtime.fs.existsSync(summaryPath)) {
    try {
      const existing = JSON.parse(runtime.fs.readFileSync(summaryPath, "utf8"));
      summary = normalizeSummaryFile(existing, summaryPath);
    } catch (error) {
      runtime.error(
        `Error: Unable to parse existing summary file: ${summaryPath}`,
      );
      if (error instanceof Error) runtime.error(error.message);
      return 1;
    }
  } else {
    const runDate = parsed.runDate ?? new Date().toISOString();
    summary = { runDate, entries: [] };
  }

  // Add new entry and write file
  summary.entries.push(entry);

  runtime.fs.mkdirSync(runtime.path.dirname(summaryPath), { recursive: true });
  runtime.fs.writeFileSync(
    summaryPath,
    `${JSON.stringify(summary, null, 2)}\n`,
    "utf8",
  );

  runtime.log(`-> Appended entry: ${inputPath}`);
  runtime.log(`   Summary JSON:   ${summaryPath}`);

  return 0;
}

// Helper functions

// Parses the arguments sent in
function parseArgs(args: string[]): ParsedArgs {
  const parsed: ParsedArgs = {
    help: false,
    errors: [],
  };

  for (let i = 0; i < args.length; i += 1) {
    const arg = args[i];
    if (arg === "--help" || arg === "-h") {
      parsed.help = true;
      return parsed;
    }

    // Summary arg
    if (arg === "--summary-json") {
      const value = args[i + 1];
      if (!value) parsed.errors.push("Error: Missing value for --summary-json");
      else parsed.summaryJson = value;
      i += 1;
      continue;
    }
    if (arg.startsWith("--summary-json=")) {
      const value = arg.slice("--summary-json=".length);
      if (!value) parsed.errors.push("Error: Missing value for --summary-json");
      else parsed.summaryJson = value;
      continue;
    }

    // Input arg
    if (arg === "--input") {
      const value = args[i + 1];
      if (!value) parsed.errors.push("Error: Missing value for --input");
      else parsed.input = value;
      i += 1;
      continue;
    }
    if (arg.startsWith("--input=")) {
      const value = arg.slice("--input=".length);
      if (!value) parsed.errors.push("Error: Missing value for --input");
      else parsed.input = value;
      continue;
    }

    // Plan arg
    if (arg === "--plan") {
      const value = args[i + 1];
      if (!value) parsed.errors.push("Error: Missing value for --plan");
      else parsed.plan = value;
      i += 1;
      continue;
    }
    if (arg.startsWith("--plan=")) {
      const value = arg.slice("--plan=".length);
      if (!value) parsed.errors.push("Error: Missing value for --plan");
      else parsed.plan = value;
      continue;
    }

    // Test arg
    if (arg === "--test") {
      const value = args[i + 1];
      if (!value) parsed.errors.push("Error: Missing value for --test");
      else parsed.test = value;
      i += 1;
      continue;
    }
    if (arg.startsWith("--test=")) {
      const value = arg.slice("--test=".length);
      if (!value) parsed.errors.push("Error: Missing value for --test");
      else parsed.test = value;
      continue;
    }

    // Date arg
    if (arg === "--run-date") {
      const value = args[i + 1];
      if (!value) parsed.errors.push("Error: Missing value for --run-date");
      else parsed.runDate = value;
      i += 1;
      continue;
    }
    if (arg.startsWith("--run-date=")) {
      const value = arg.slice("--run-date=".length);
      if (!value) parsed.errors.push("Error: Missing value for --run-date");
      else parsed.runDate = value;
      continue;
    }

    if (arg.startsWith("-")) {
      parsed.errors.push(`Error: Unknown option: ${arg}`);
      continue;
    }

    parsed.errors.push(`Error: Unexpected argument: ${arg}`);
  }

  return parsed;
}

// Prints usage instructions
function printUsage(log: (...args: unknown[]) => void): void {
  log("Usage:");
  log(
    "  npx append-json-summary-entry --summary-json <path> --input <ac-file> --plan <plan.json> --test <spec.ts>",
  );
  log("");
  log("Optional:");
  log("  --run-date <iso>");
}

// Converts each test in the plan into a summary entry
function buildTestSummaries(plan: TestSuite): SummaryEntry["tests"] {
  return plan.tests.map((test) => ({
    name: test.name,
    requiredTestHooks: extractHooks(test.steps),
  }));
}

// Collects all hooks a test uses, deduped, in the order seen
function extractHooks(steps: TestSuite["tests"][number]["steps"]): string[] {
  const hooks: string[] = [];
  const seen = new Set<string>();

  for (const step of steps) {
    if ("target" in step && typeof step.target === "string") {
      const hook = step.target;
      if (!seen.has(hook)) {
        seen.add(hook);
        hooks.push(hook);
      }
    }
  }

  return hooks;
}

// Extracts a summary file so more can be added to it
function normalizeSummaryFile(input: unknown, filePath: string): SummaryFile {
  if (
    !input ||
    typeof input !== "object" ||
    Array.isArray(input) ||
    !("runDate" in input) ||
    !("entries" in input)
  ) {
    throw new Error(`Invalid summary file format: ${filePath}`);
  }

  const runDate = (input as SummaryFile).runDate;
  const entries = (input as SummaryFile).entries;

  if (typeof runDate !== "string" || !Array.isArray(entries)) {
    throw new Error(`Invalid summary file format: ${filePath}`);
  }

  return { runDate, entries };
}

// @internal exports for unit tests
export {
  buildTestSummaries as _buildTestSummaries,
  extractHooks as _extractHooks,
  normalizeSummaryFile as _normalizeSummaryFile,
  parseArgs as _parseArgs,
};

#!/usr/bin/env node

import fs from "node:fs";
import path from "node:path";
import { handleCliCommonErrors } from "../utils/cli";

// Explicit types matching actual usage patterns (instead of Pick<typeof fs, ...>)
// This allows TypeScript to properly type-check mocks without overload ambiguity
type FsSubset = {
  readFileSync: (
    path: fs.PathOrFileDescriptor,
    encoding: BufferEncoding,
  ) => string;
  mkdirSync: (
    path: fs.PathLike,
    options?: fs.MakeDirectoryOptions,
  ) => string | undefined;
  writeFileSync: (
    path: fs.PathOrFileDescriptor,
    data: string | NodeJS.ArrayBufferView,
    options?: fs.WriteFileOptions,
  ) => void;
};

type PathSubset = {
  dirname: (path: string) => string;
};

export type CliRuntime = {
  fs: FsSubset;
  path: PathSubset;
  log: (...args: unknown[]) => void;
  error: (...args: unknown[]) => void;
};

const defaultRuntime: CliRuntime = {
  fs,
  path,
  log: console.log,
  error: console.error,
};

type SummaryEntry = {
  input: string;
  outputs: {
    plan: string;
    test: string;
  };
  tests: Array<{
    name: string;
    requiredTestHooks: string[];
  }>;
};

type SummaryFile = {
  runDate: string;
  entries: SummaryEntry[];
};

type ParsedArgs = {
  summaryJson?: string;
  summaryMd?: string;
  help: boolean;
  errors: string[];
};

// CLI entrypoint
if (require.main === module) {
  const code = run(process.argv);
  process.exit(code);
}

export function run(
  argv: string[],
  runtime: CliRuntime = defaultRuntime,
): number {
  // Parse args
  const parsed = parseArgs(argv.slice(2));
  const exitCode = handleCliCommonErrors({
    parsed,
    runtime,
    printUsage,
    required: {
      summaryJson: "Error: Missing required option: --summary-json <path>",
      summaryMd: "Error: Missing required option: --summary-md <path>",
    },
  });
  if (exitCode >= 0) return exitCode;
  if (!parsed.summaryJson || !parsed.summaryMd) return 1;

  // Grab the summary file
  let summary: SummaryFile;
  try {
    const raw = runtime.fs.readFileSync(parsed.summaryJson, "utf8");
    const parsedJson = JSON.parse(raw);
    summary = normalizeSummaryFile(parsedJson, parsed.summaryJson);
  } catch (error) {
    runtime.error(
      `Error: Unable to read summary JSON file: ${parsed.summaryJson}`,
    );
    if (error instanceof Error) runtime.error(error.message);
    return 1;
  }

  // Build the text and write the file
  const inputs = uniqueInOrder(summary.entries.map((entry) => entry.input));
  const outputs = uniqueInOrder(
    summary.entries.map((entry) => entry.outputs.test),
  );
  const requiredHooksByTestFile = collectRequiredHooksByTestFile(
    summary.entries,
  );

  const markdown = renderMarkdown({
    runDate: summary.runDate,
    inputs,
    outputs,
    requiredHooksByTestFile,
  });

  runtime.fs.mkdirSync(runtime.path.dirname(parsed.summaryMd), {
    recursive: true,
  });
  runtime.fs.writeFileSync(parsed.summaryMd, markdown, "utf8");

  runtime.log(`-> Wrote: ${parsed.summaryMd}`);
  return 0;
}

// Helper functions

// Parses the arguments sent in
function parseArgs(args: string[]): ParsedArgs {
  const parsed: ParsedArgs = {
    help: false,
    errors: [],
  };

  for (let i = 0; i < args.length; i += 1) {
    const arg = args[i];
    if (arg === "--help" || arg === "-h") {
      parsed.help = true;
      return parsed;
    }

    // Summary arg (json input)
    if (arg === "--summary-json") {
      const value = args[i + 1];
      if (!value) parsed.errors.push("Error: Missing value for --summary-json");
      else parsed.summaryJson = value;
      i += 1;
      continue;
    }
    if (arg.startsWith("--summary-json=")) {
      const value = arg.slice("--summary-json=".length);
      if (!value) parsed.errors.push("Error: Missing value for --summary-json");
      else parsed.summaryJson = value;
      continue;
    }

    // Summary arg (md output)
    if (arg === "--summary-md") {
      const value = args[i + 1];
      if (!value) parsed.errors.push("Error: Missing value for --summary-md");
      else parsed.summaryMd = value;
      i += 1;
      continue;
    }
    if (arg.startsWith("--summary-md=")) {
      const value = arg.slice("--summary-md=".length);
      if (!value) parsed.errors.push("Error: Missing value for --summary-md");
      else parsed.summaryMd = value;
      continue;
    }

    if (arg.startsWith("-")) {
      parsed.errors.push(`Error: Unknown option: ${arg}`);
      continue;
    }

    parsed.errors.push(`Error: Unexpected argument: ${arg}`);
  }

  return parsed;
}

// Prints usage instructions
function printUsage(log: (...args: unknown[]) => void): void {
  log("Usage:");
  log(
    "  npx create-markdown-summary --summary-json <path> --summary-md <path>",
  );
}

// Validates summary json structure
function normalizeSummaryFile(input: unknown, filePath: string): SummaryFile {
  if (
    !input ||
    typeof input !== "object" ||
    Array.isArray(input) ||
    !("runDate" in input) ||
    !("entries" in input)
  ) {
    throw new Error(`Invalid summary file format: ${filePath}`);
  }

  const runDate = (input as SummaryFile).runDate;
  const entries = (input as SummaryFile).entries;

  if (typeof runDate !== "string" || !Array.isArray(entries)) {
    throw new Error(`Invalid summary file format: ${filePath}`);
  }

  return { runDate, entries };
}

// Dedupes while preserving order
function uniqueInOrder(items: string[]): string[] {
  const seen = new Set<string>();
  const result: string[] = [];

  for (const item of items) {
    if (!seen.has(item)) {
      seen.add(item);
      result.push(item);
    }
  }

  return result;
}

// Writes the markdown
function renderMarkdown(data: {
  runDate: string;
  inputs: string[];
  outputs: string[];
  requiredHooksByTestFile: Map<
    string,
    Array<{ name: string; hooks: string[] }>
  >;
}): string {
  const lines: string[] = [];

  lines.push("# Post-creation summary");
  lines.push("");
  lines.push(`- Run date: ${data.runDate}`);
  lines.push("");
  lines.push("## Inputs: AC files");
  lines.push(...renderList(data.inputs));
  lines.push("");
  lines.push("## Outputs: Playwright test files");
  lines.push(...renderList(data.outputs));
  lines.push("");
  lines.push("## Next steps");
  lines.push(
    "- Copy the generated Playwright spec files AND the fixtures/ directory into your project repo. The spec files import test utilities from fixtures/ and will fail to compile without it.",
  );
  lines.push(
    "- Ensure the codebase includes the required test hooks (data-testid attributes on the appropriate elements). If there's any ambiguity, review the input AC file alongside the JSON plan to most easily see the intended test flow and targets.",
  );
  lines.push(
    "- If Playwright isn't yet configured for your project and you requested the config template, copy it to your repo root and adjust baseURL, testDir, and reporter/output paths to match your project.",
  );
  lines.push(
    "- Consider reviewing your Vitest (or other) test configs to make sure these new Playwright *.spec.ts files won't get picked up with other testing.",
  );
  lines.push(
    "- Add a CI step to run Playwright and upload traces/screenshots on failure.",
  );
  lines.push("");
  lines.push("## Required test hooks");
  if (data.requiredHooksByTestFile.size === 0) {
    lines.push("- (none)");
  } else {
    for (const [testFile, tests] of data.requiredHooksByTestFile) {
      lines.push(`- ${testFile}`);
      for (const test of tests) {
        lines.push(`  - ${test.name}`);
        for (const hook of test.hooks) {
          lines.push(`    - ${hook}`);
        }
      }
    }
  }
  lines.push("");

  return `${lines.join("\n")}`;
}

// Helps with bullets
function renderList(items: string[]): string[] {
  if (items.length === 0) {
    return ["- (none)"];
  }
  return items.map((item) => `- ${item}`);
}

// Collects required hooks grouped by output test file in entry order.
function collectRequiredHooksByTestFile(
  entries: SummaryEntry[],
): Map<string, Array<{ name: string; hooks: string[] }>> {
  const output = new Map<string, Array<{ name: string; hooks: string[] }>>();

  for (const entry of entries) {
    const testsWithHooks = entry.tests
      .filter((test) => test.requiredTestHooks.length > 0)
      .map((test) => ({ name: test.name, hooks: test.requiredTestHooks }));

    if (testsWithHooks.length === 0) continue;
    output.set(entry.outputs.test, testsWithHooks);
  }

  return output;
}

// @internal exports for unit tests
export {
  collectRequiredHooksByTestFile as _collectRequiredHooksByTestFile,
  normalizeSummaryFile as _normalizeSummaryFile,
  parseArgs as _parseArgs,
  renderMarkdown as _renderMarkdown,
  uniqueInOrder as _uniqueInOrder,
};

#!/usr/bin/env node

// This cli script allows a user to specify the location of a json test plan
// and kick off creation of Playwright test files.

import fs from "node:fs";
import path from "node:path";
import { z } from "zod";
import { testSuiteSchema } from "../plan-schema";
import { type PlanFile, translatePlan } from "../translate-plan-to-tests";
import { handleCliCommonErrors } from "../utils/cli";
import { run as appendSummaryEntry } from "./append-json-summary-entry";
import { run as createMarkdownSummary } from "./create-markdown-summary";

// Types
// Explicit types matching actual usage patterns (instead of Pick<typeof fs, ...>)
// This allows TypeScript to properly type-check mocks without overload ambiguity
type FsSubset = {
  existsSync: (path: fs.PathLike) => boolean;
  statSync: (path: fs.PathLike) => fs.Stats;
  // Explicitly type the withFileTypes overload used in expandSegment()
  readdirSync: (
    path: fs.PathLike,
    options: { withFileTypes: true }
  ) => fs.Dirent[];
  readFileSync: (
    path: fs.PathOrFileDescriptor,
    encoding: BufferEncoding,
  ) => string;
  mkdirSync: (
    path: fs.PathLike,
    options?: fs.MakeDirectoryOptions,
  ) => string | undefined;
  writeFileSync: (
    path: fs.PathOrFileDescriptor,
    data: string | NodeJS.ArrayBufferView,
    options?: fs.WriteFileOptions,
  ) => void;
};

type PathSubset = {
  resolve: (...paths: string[]) => string;
  dirname: (path: string) => string;
  basename: (path: string, suffix?: string) => string;
  join: (...paths: string[]) => string;
  isAbsolute: (path: string) => boolean;
  parse: (path: string) => path.ParsedPath;
};

export type CliRuntime = {
  fs: FsSubset;
  path: PathSubset;
  appendSummaryEntry: (argv: string[]) => number;
  createMarkdownSummary: (argv: string[]) => number;
  now: () => Date;
  log: (...args: unknown[]) => void;
  error: (...args: unknown[]) => void;
};

const defaultRuntime: CliRuntime = {
  fs,
  path,
  appendSummaryEntry,
  createMarkdownSummary,
  now: () => new Date(),
  log: console.log,
  error: console.error,
};

// CLI entrypoint
if (require.main === module) {
  const code = run(process.argv);
  process.exit(code);
}

export function run(
  argv: string[],
  runtime: CliRuntime = defaultRuntime,
): number {
  // Parse args
  const parsed = parseArgs(argv.slice(2));
  const exitCode = handleCliCommonErrors({
    parsed,
    runtime,
    printUsage,
    required: {
      testsDir: "Error: Missing required option: --tests-dir <path>",
      summaryDir: "Error: Missing required option: --summary-dir <path>",
    },
  });
  if (exitCode >= 0) return exitCode;
  if (!parsed.testsDir || !parsed.summaryDir) return 1;

  const summaryJsonPath = runtime.path.join(
    parsed.summaryDir,
    formatSummaryFilename(runtime.now()),
  );

  // Reads inputs
  const inputs = parsed.inputs;

  const files: string[] = [];

  for (const input of inputs) {
    let matches: string[] = [];

    try {
      matches = processInput(input, runtime);
    } catch (e) {
      runtime.error(e instanceof Error ? e.message : String(e));
      return 1;
    }

    // Warn if any globs matched nothing
    if (input.includes("*") && matches.length === 0) {
      runtime.error(`Warning: Glob pattern matched no files: ${input}`);
    }
    files.push(...matches);
  }

  // Errors if no inputs were given or resolved from globs
  if (files.length === 0) {
    runtime.error(
      "Error: Missing inputs. Please submit input file(s) separated by spaces.",
    );
    printUsage(runtime.error);
    return 1;
  }

  // Normalize inputs (keep both original + resolved)
  const inputPairs = files.map((original) => ({
    original,
    resolved: runtime.path.resolve(original),
  }));

  // Deduplicate by resolved path (preserve first original)
  const seen = new Set<string>();
  const uniquePairs: typeof inputPairs = [];

  for (const pair of inputPairs) {
    if (!seen.has(pair.resolved)) {
      seen.add(pair.resolved);
      uniquePairs.push(pair);
    }
  }

  // Errors if dotfiles or dotdirs are passed in as inputs
  const hidden = uniquePairs.filter((p) => hasHiddenSegment(p.original));
  if (hidden.length) {
    runtime.error("Error: Hidden files and dirs are not allowed as inputs:");
    for (const h of hidden) runtime.error(`  ${h.original}`);
    return 1;
  }

  // Errors if specific input files aren't found
  const missing = uniquePairs.filter((p) => !runtime.fs.existsSync(p.resolved));
  if (missing.length) {
    runtime.error("Error: Input file(s) not found.");
    for (const m of missing) runtime.error(`  ${m.original}`);
    return 1;
  }

  // Creates test files from inputs
  for (const { original, resolved } of uniquePairs) {
    const rawPlan = runtime.fs.readFileSync(resolved, "utf8");

    let parsedPlan: unknown;
    try {
      parsedPlan = JSON.parse(rawPlan);
    } catch {
      runtime.error(`Invalid JSON: ${original}`);
      return 1;
    }

    const validationResult = testSuiteSchema.safeParse(parsedPlan);
    if (!validationResult.success) {
      runtime.error(`Invalid test suite: ${original}`);
      runtime.error(z.prettifyError(validationResult.error));
      return 1;
    }

    const planFile = parsedPlan as PlanFile;
    const testFile = translatePlan(planFile, { outDir: parsed.testsDir });

    runtime.fs.mkdirSync(runtime.path.dirname(testFile.path), {
      recursive: true,
    });
    runtime.fs.writeFileSync(testFile.path, testFile.content, "utf8");
    runtime.log(`-> Read:        ${original}`);
    runtime.log(`   Wrote:       ${testFile.path}`);
    runtime.log(`   To run, do:  npx playwright test ${testFile.path}`);

    const appendCode = runtime.appendSummaryEntry([
      "node",
      "append-json-summary-entry.js",
      "--summary-json",
      summaryJsonPath,
      "--input",
      testFile.sourceDescription,
      "--plan",
      original,
      "--test",
      testFile.path,
    ]);
    if (appendCode !== 0) {
      runtime.error("Error: Failed to append summary entry.");
      return 1;
    }
  }

  const summaryMdPath = summaryJsonPath.replace(/\.json$/, ".md");
  const markdownCode = runtime.createMarkdownSummary([
    "node",
    "create-markdown-summary.js",
    "--summary-json",
    summaryJsonPath,
    "--summary-md",
    summaryMdPath,
  ]);
  if (markdownCode !== 0) {
    runtime.error("Error: Failed to create markdown summary.");
    return 1;
  }

  return 0;
}

// Helper functions

type ParsedArgs = {
  inputs: string[];
  testsDir?: string;
  summaryDir?: string;
  help: boolean;
  errors: string[];
};

function parseArgs(args: string[]): ParsedArgs {
  const parsed: ParsedArgs = {
    inputs: [],
    help: false,
    errors: [],
  };

  for (let i = 0; i < args.length; i += 1) {
    const arg = args[i];
    if (arg === "--help" || arg === "-h") {
      parsed.help = true;
      return parsed;
    }

    if (arg === "--tests-dir") {
      const value = args[i + 1];
      if (!value) {
        parsed.errors.push("Error: Missing value for --tests-dir");
      } else {
        parsed.testsDir = value;
        i += 1;
      }
      continue;
    }

    if (arg.startsWith("--tests-dir=")) {
      const value = arg.slice("--tests-dir=".length);
      if (!value) parsed.errors.push("Error: Missing value for --tests-dir");
      else parsed.testsDir = value;
      continue;
    }

    if (arg === "--summary-dir") {
      const value = args[i + 1];
      if (!value) {
        parsed.errors.push("Error: Missing value for --summary-dir");
      } else {
        parsed.summaryDir = value;
        i += 1;
      }
      continue;
    }

    if (arg.startsWith("--summary-dir=")) {
      const value = arg.slice("--summary-dir=".length);
      if (!value) parsed.errors.push("Error: Missing value for --summary-dir");
      else parsed.summaryDir = value;
      continue;
    }

    if (arg.startsWith("-")) {
      parsed.errors.push(`Error: Unknown option: ${arg}`);
      continue;
    }

    parsed.inputs.push(arg);
  }

  return parsed;
}

function printUsage(log: (...args: unknown[]) => void): void {
  log("Usage:");
  log(
    "  npx generate-tests <plan.json> [more plans...] --tests-dir <path> --summary-dir <path>",
  );
}

// Checks if a path has dotfiles or dotdirs
function hasHiddenSegment(filePath: string): boolean {
  const normalized = filePath.replace(/\\/g, "/");
  const segments = normalized.split("/").filter(Boolean);
  return segments.some((s) => s.startsWith(".") && s !== "." && s !== "..");
}

// Escapes regex chars to make a string safe to include in regex
function escapeRegex(s: string): string {
  return s.replace(/[.*+^${}()|[\]\\]/g, "\\$&");
}

// Converts a filename with * into regex
function starPatternToRegex(pattern: string): RegExp {
  const escaped = escapeRegex(pattern).replace(/\\\*/g, ".*");
  return new RegExp(`^${escaped}$`);
}

// Checks input for globs and processes them appropriately
// Mac/most Linux (bash) does this automatically at the command line
// This ensures parallel functionality for Windows and Linux non-bash users
function processInput(input: string, runtime: CliRuntime): string[] {
  const { fs, path } = runtime;

  // It's a literal path
  if (!input.includes("*")) return [input];

  // No recursion
  if (input.includes("**")) {
    throw new Error(`Error: Unsupported: recursive glob (**): ${input}`);
  }

  const isAbs = path.isAbsolute(input);
  const root = isAbs ? path.parse(input).root : "";
  const normalizedInput = input.replace(/\\/g, "/");
  const normalizedRoot = root.replace(/\\/g, "/");

  const relativePart = isAbs
    ? normalizedInput.slice(normalizedRoot.length)
    : normalizedInput;

  // Expand wildcards
  const segments = relativePart.split("/").filter(Boolean);
  let currentPaths: string[] = [isAbs ? root : process.cwd()];

  for (const segment of segments) {
    currentPaths = expandSegment(currentPaths, segment, runtime);
    if (currentPaths.length === 0) return [];
  }

  // Keep only files (and exclude dotfiles defensively)
  const finalFiles = currentPaths
    .filter((p) => {
      const name = path.basename(p);
      if (name.startsWith(".")) return false;
      return fs.existsSync(p) && fs.statSync(p).isFile();
    })
    .sort();

  return finalFiles;
}

function formatSummaryFilename(now: Date): string {
  const iso = now.toISOString().replace(/\.\d{3}Z$/, "Z");
  return `${iso.replace("T", "-").replace(/:/g, "-")}-summary.json`;
}

// Expands a given segment of an input path that has a glob
function expandSegment(
  basePaths: string[],
  segment: string,
  runtime: CliRuntime,
): string[] {
  const { fs, path } = runtime;

  // If no wildcard, just append this segment to every base path
  if (!segment.includes("*")) {
    return basePaths.map((base) => path.join(base, segment));
  }

  const segmentRegex = starPatternToRegex(segment);
  const matches: string[] = [];

  for (const base of basePaths) {
    if (!fs.existsSync(base) || !fs.statSync(base).isDirectory()) continue;

    for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
      if (entry.name.startsWith(".")) continue; // exclude dotfiles + dotdirs
      if (!segmentRegex.test(entry.name)) continue; // does it match?
      matches.push(path.join(base, entry.name));
    }
  }

  return matches.sort();
}

// @internal exports for unit tests
export {
  escapeRegex as _escapeRegex,
  expandSegment as _expandSegment,
  hasHiddenSegment as _hasHiddenSegment,
  processInput as _processInput,
  starPatternToRegex as _starPatternToRegex,
  parseArgs as _parseArgs,
  formatSummaryFilename as _formatSummaryFilename,
};

#!/usr/bin/env node

import fs from "node:fs";
import { testSuiteSchema } from "../plan-schema";

// Explicit types matching actual usage patterns (instead of Pick<typeof fs, ...>)
// This allows TypeScript to properly type-check mocks without overload ambiguity
export type Runtime = {
  fs: {
    readFileSync: (
      path: fs.PathOrFileDescriptor,
      encoding: BufferEncoding,
    ) => string;
  };
  log: (...args: unknown[]) => void;
  error: (...args: unknown[]) => void;
};

const defaultRuntime: Runtime = {
  fs,
  log: console.log,
  error: console.error,
};

export function run(argv: string[], runtime: Runtime = defaultRuntime): number {
  const filePath = argv[2];
  if (!filePath) {
    runtime.error("Usage: npx validate-plan path/to/plan.json");
    return 1;
  }

  const raw = runtime.fs.readFileSync(filePath, "utf8");
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    runtime.error("Invalid JSON");
    return 1;
  }

  const result = testSuiteSchema.safeParse(parsed);
  if (!result.success) {
    runtime.error(JSON.stringify(result.error.format(), null, 2));
    return 1;
  }

  runtime.log("JSON passed validation");
  return 0;
}

if (require.main === module) {
  process.exit(run(process.argv));
}

import { z } from "zod";

/**
 * Valid Playwright keyboard key names
 * Source: https://playwright.dev/docs/api/class-keyboard#keyboard-press
 */
export const validPlaywrightKeys = [
  "Enter",
  "Tab",
  "Escape",
  "Backspace",
  "Delete",
  "ArrowLeft",
  "ArrowRight",
  "ArrowUp",
  "ArrowDown",
  "Home",
  "End",
  "PageUp",
  "PageDown",
  "Insert",
  "Space",
  "F1",
  "F2",
  "F3",
  "F4",
  "F5",
  "F6",
  "F7",
  "F8",
  "F9",
  "F10",
  "F11",
  "F12",
  "Shift",
  "Control",
  "Alt",
  "Numpad0",
  "Numpad1",
  "Numpad2",
  "Numpad3",
  "Numpad4",
  "Numpad5",
  "Numpad6",
  "Numpad7",
  "Numpad8",
  "Numpad9",
  "NumpadAdd",
  "NumpadSubtract",
  "NumpadDecimal",
  "NumpadEnter",
] as const;

/**
 * Characters that can be typed without holding Shift on a US keyboard
 */
const unmodifiedCharacters = "abcdefghijklmnopqrstuvwxyz0123456789`-=[]\\;',./";

/**
 * Zod validator for keyboard keys for presses
 * Accepts either:
 * - A single unmodified character (no Shift required on US keyboard)
 * - A valid Playwright key name from the list above (case-insensitive)
 */
export const pressKeyValidator = z.string().transform((val, ctx) => {
  // Single characters must match exactly (case-sensitive)
  if (val.length === 1) {
    if (unmodifiedCharacters.includes(val)) {
      return val;
    }
    ctx.addIssue({
      code: "custom",
      message: "Key must be a single unmodified character (a-z, 0-9, or symbols that don't require Shift) or a valid Playwright key name (e.g., Enter, Tab, Escape, Space, ArrowLeft, F1, etc.).",
    });
    return z.NEVER;
  }

  // Named keys: case-insensitive lookup, return canonical casing
  const lowerInput = val.toLowerCase();
  const matchedKey = validPlaywrightKeys.find(k => k.toLowerCase() === lowerInput);

  if (matchedKey) {
    return matchedKey;
  }

  ctx.addIssue({
    code: "custom",
    message: "Key must be a single unmodified character (a-z, 0-9, or symbols that don't require Shift) or a valid Playwright key name (e.g., Enter, Tab, Escape, Space, ArrowLeft, F1, etc.).",
  });
  return z.NEVER;
});

/**
 * Valid modifier keys for the application under test
 * These are the only keys that can be held down with keyDown/keyUp actions
 */
export const validModifierKeys = ["Shift", "Control", "a"] as const;

/**
 * Zod validator for modifier keys (keyDown/keyUp actions)
 * Only accepts the specific modifier keys used by the application under test (case-insensitive)
 */
export const modifierKeyValidator = z.string().transform((val, ctx) => {
  // Case-insensitive lookup, return canonical casing
  const lowerInput = val.toLowerCase();
  const matchedKey = validModifierKeys.find(k => k.toLowerCase() === lowerInput);

  if (matchedKey) {
    return matchedKey;
  }

  ctx.addIssue({
    code: "custom",
    message: 'Key must be one of the valid modifier keys for this application: "Shift", "Control", or "a".',
  });
  return z.NEVER;
});

import { z } from "zod";

/**
 * Valid mouse button types
 */
export const validMouseButtons = ["left", "right", "middle"] as const;

/**
 * Zod validator for mouse button parameter
 */
export const mouseButtonValidator = z.enum(validMouseButtons);

/**
 * Valid mouse wheel scroll directions
 */
export const validWheelDirections = ["up", "down", "left", "right"] as const;

/**
 * Zod validator for mouse wheel direction parameter
 */
export const wheelDirectionValidator = z.enum(validWheelDirections);

import { z } from "zod";
import { modifierKeyValidator, pressKeyValidator } from "./keyboard-key-validator";
import { mouseButtonValidator, wheelDirectionValidator } from "./mouse-validator";
import { tagValidator } from "./tag-validator";
import { targetValidator } from "./target-validator";

/**
 * Step schemas
 */
const clickStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("click"),
  target: targetValidator,
}).strict();

const doubleClickStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("doubleClick"),
  x: z.number().int().min(0),
  y: z.number().int().min(0),
  button: mouseButtonValidator.optional().default("left"),
}).strict();

const dragStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("drag"),
  fromX: z.number().int().min(0),
  fromY: z.number().int().min(0),
  toX: z.number().int().min(0),
  toY: z.number().int().min(0),
  button: mouseButtonValidator.optional().default("left"),
}).strict();

const expectNotVisibleStep = z.object({
  type: z.literal("assertion").default("assertion"),
  action: z.literal("expectNotVisible"),
  target: targetValidator,
}).strict();

const expectTextStep = z.object({
  type: z.literal("assertion").default("assertion"),
  action: z.literal("expectText"),
  target: targetValidator,
  value: z.string(),
}).strict();

const expectUrlStep = z.object({
  type: z.literal("assertion").default("assertion"),
  action: z.literal("expectUrl"),
  value: z.string(),
}).strict();

const expectVisibleStep = z.object({
  type: z.literal("assertion").default("assertion"),
  action: z.literal("expectVisible"),
  target: targetValidator,
}).strict();

const fillStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("fill"),
  target: targetValidator,
  value: z.string(),
}).strict();

const gotoStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("goto"),
  value: z.string(),
}).strict();

const hoverStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("hover"),
  target: targetValidator,
}).strict();

const keyDownStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("keyDown"),
  value: modifierKeyValidator,
}).strict();

const keyUpStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("keyUp"),
  value: modifierKeyValidator,
}).strict();

const mouseClickStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("mouseClick"),
  x: z.number().int().min(0),
  y: z.number().int().min(0),
  button: mouseButtonValidator.optional().default("left"),
}).strict();

const mouseDownStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("mouseDown"),
  button: mouseButtonValidator.optional().default("left"),
}).strict();

const mouseMoveStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("mouseMove"),
  x: z.number().int().min(0),
  y: z.number().int().min(0),
}).strict();

const mouseUpStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("mouseUp"),
  button: mouseButtonValidator.optional().default("left"),
}).strict();

const pressStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("press"),
  value: pressKeyValidator,
}).strict();

const reloadStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("reload"),
}).strict();

const scrollStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("scroll"),
  direction: wheelDirectionValidator,
  amount: z.number().int().positive(),
}).strict();

const selectStep = z.object({
  type: z.literal("action").default("action"),
  action: z.literal("select"),
  target: targetValidator,
  value: z.string(),
}).strict();

export const stepSchema = z.discriminatedUnion("action", [
  clickStep,
  doubleClickStep,
  dragStep,
  expectNotVisibleStep,
  expectTextStep,
  expectUrlStep,
  expectVisibleStep,
  fillStep,
  gotoStep,
  hoverStep,
  keyDownStep,
  keyUpStep,
  mouseClickStep,
  mouseDownStep,
  mouseMoveStep,
  mouseUpStep,
  pressStep,
  reloadStep,
  scrollStep,
  selectStep,
]);

/**
 * Test + Suite schemas
 */
export const testSchema = z.object({
  name: z.string(),
  startUrl: z.string(),
  tags: z.array(tagValidator).min(1).optional(),
  steps: z.array(stepSchema).min(1),
}).superRefine((test, ctx) => {
  let unpairedMouseDown: { index: number; button: string } | null = null;
  let unpairedKeyDown: { index: number; value: string } | null = null;
  let hasError = false;

  for (let index = 0; index < test.steps.length; index++) {
    const step = test.steps[index];
    if (step.action === "mouseDown") {
      // If there's already an unpaired mouseDown, that's an error (regardless of button)
      if (unpairedMouseDown !== null) {
        ctx.addIssue({
          code: "custom",
          message: `mouseDown at step ${index} occurs before completing the previous mouseDown at step ${unpairedMouseDown.index}. Each mouseDown must be followed by exactly one mouseUp before another mouseDown.`,
          path: ["steps", index, "action"],
        });
        hasError = true;
        break;
      }
      // Track the button that was pressed (schema guarantees button exists via default)
      unpairedMouseDown = { index, button: step.button };
    } else if (step.action === "mouseUp") {
      // mouseUp without a preceding unpaired mouseDown is an error
      if (unpairedMouseDown === null) {
        ctx.addIssue({
          code: "custom",
          message: `mouseUp at step ${index} has no preceding mouseDown. mouseUp requires a mouseDown action earlier in the steps array.`,
          path: ["steps", index, "action"],
        });
        hasError = true;
        break;
      } else {
        // Check that the button matches (schema guarantees button exists via default)
        if (step.button !== unpairedMouseDown.button) {
          ctx.addIssue({
            code: "custom",
            message: `mouseUp at step ${index} uses button "${step.button}" but the paired mouseDown at step ${unpairedMouseDown.index} used button "${unpairedMouseDown.button}". The button must match between mouseDown and mouseUp.`,
            path: ["steps", index, "button"],
          });
          hasError = true;
          break;
        }
        // Pair completed, reset tracker
        unpairedMouseDown = null;
      }
    } else if (step.action === "keyDown") {
      // If there's already an unpaired keyDown, that's an error
      if (unpairedKeyDown !== null) {
        ctx.addIssue({
          code: "custom",
          message: `keyDown at step ${index} occurs before completing the previous keyDown at step ${unpairedKeyDown.index}. Each keyDown must be followed by exactly one keyUp before another keyDown.`,
          path: ["steps", index, "action"],
        });
        hasError = true;
        break;
      }
      // Track the modifier key that was pressed
      unpairedKeyDown = { index, value: step.value };
    } else if (step.action === "keyUp") {
      // keyUp without a preceding unpaired keyDown is an error
      if (unpairedKeyDown === null) {
        ctx.addIssue({
          code: "custom",
          message: `keyUp at step ${index} has no preceding keyDown. keyUp requires a keyDown action earlier in the steps array.`,
          path: ["steps", index, "action"],
        });
        hasError = true;
        break;
      } else {
        // Check that the modifier key matches
        if (step.value !== unpairedKeyDown.value) {
          ctx.addIssue({
            code: "custom",
            message: `keyUp at step ${index} uses key "${step.value}" but the paired keyDown at step ${unpairedKeyDown.index} used key "${unpairedKeyDown.value}". The modifier key must match between keyDown and keyUp.`,
            path: ["steps", index, "value"],
          });
          hasError = true;
          break;
        }
        // Pair completed, reset tracker
        unpairedKeyDown = null;
      }
    }
  }

  // After processing all steps, check if there's an unpaired mouseDown (only if no error yet)
  if (!hasError && unpairedMouseDown !== null) {
    ctx.addIssue({
      code: "custom",
      message: `mouseDown at step ${unpairedMouseDown.index} has no following mouseUp. Each mouseDown must be followed by exactly one mouseUp.`,
      path: ["steps", unpairedMouseDown.index, "action"],
    });
  }

  // Check if there's an unpaired keyDown (only if no error yet)
  if (!hasError && unpairedKeyDown !== null) {
    ctx.addIssue({
      code: "custom",
      message: `keyDown at step ${unpairedKeyDown.index} has no following keyUp. Each keyDown must be followed by exactly one keyUp.`,
      path: ["steps", unpairedKeyDown.index, "action"],
    });
  }

  // Validate visibility assertion pairing
  if (!hasError) {
    // Helper to check if a step is an action (not an assertion)
    const isAction = (step: z.infer<typeof stepSchema>): boolean => {
      return step.type === "action";
    };

    // Helper to count actions between two indices
    const countActionsBetween = (startIndex: number, endIndex: number): number => {
      let count = 0;
      for (let i = startIndex + 1; i < endIndex; i++) {
        if (isAction(test.steps[i])) {
          count++;
        }
      }
      return count;
    };

    // Group visibility assertions by target
    const assertionsByTarget = new Map<string, Array<{
      index: number;
      action: "expectVisible" | "expectNotVisible";
    }>>();

    test.steps.forEach((step, index) => {
      if (step.action === "expectVisible" || step.action === "expectNotVisible") {
        const targetAssertions = assertionsByTarget.get(step.target);
        if (targetAssertions) {
          targetAssertions.push({
            index,
            action: step.action,
          });
        } else {
          assertionsByTarget.set(step.target, [{
            index,
            action: step.action,
          }]);
        }
      }
    });

    // Validate each target
    for (const [target, assertions] of assertionsByTarget.entries()) {
      // Must have exactly 2 assertions
      if (assertions.length !== 2) {
        ctx.addIssue({
          code: "custom",
          message: `Target "${target}" has ${assertions.length} visibility assertion(s), but must have exactly 2 (one expectVisible and one expectNotVisible with exactly one action between them).`,
          path: ["steps"],
        });
        hasError = true;
        break;
      }

      const [first, second] = assertions;

      // Must be opposite types
      if (first.action === second.action) {
        ctx.addIssue({
          code: "custom",
          message: `Target "${target}" has two ${first.action} assertions. Visibility assertions must be opposite types (one expectVisible and one expectNotVisible).`,
          path: ["steps", second.index, "action"],
        });
        hasError = true;
        break;
      }

      // Must have exactly 1 action between them
      const actionCount = countActionsBetween(first.index, second.index);
      if (actionCount !== 1) {
        ctx.addIssue({
          code: "custom",
          message: `Target "${target}" has ${actionCount} action(s) between visibility assertions at steps ${first.index} and ${second.index}, but must have exactly 1 action.`,
          path: ["steps", second.index, "action"],
        });
        hasError = true;
        break;
      }
    }
  }
}).strict();

/**
 * Exports
*/
export const testSuiteSchema = z.object({
  suiteName: z.string(),
  tags: z.array(tagValidator).min(1).optional(),
  source: z.object({
    repo: z.string(),
    path: z.string(),
  }).strict(),
  tests: z.array(testSchema).min(1),
}).strict();

export type TestSuite = z.infer<typeof testSuiteSchema>;