ccqa 0.1.0

package/src/store/index.test.ts

@@ -0,0 +1,107 @@
+import { describe, test, expect } from "bun:test";
+import { parseSpecPath, getCcqaDir, getFeatureDir, getSpecDir, routeToMarkdown } from "./index.ts";
+import type { Route } from "../types.ts";
+
+describe("parseSpecPath", () => {
+  test("parses valid feature/spec path", () => {
+    expect(parseSpecPath("feat/spec")).toEqual({ featureName: "feat", specName: "spec" });
+    expect(parseSpecPath("tasks/create-and-complete")).toEqual({
+      featureName: "tasks",
+      specName: "create-and-complete",
+    });
+  });
+
+  test("throws on single segment", () => {
+    expect(() => parseSpecPath("feat")).toThrow();
+  });
+
+  test("throws on three segments", () => {
+    expect(() => parseSpecPath("a/b/c")).toThrow();
+  });
+
+  test("throws on empty string", () => {
+    expect(() => parseSpecPath("")).toThrow();
+  });
+
+  test("throws on empty feature name", () => {
+    expect(() => parseSpecPath("/spec")).toThrow();
+  });
+
+  test("throws on empty spec name", () => {
+    expect(() => parseSpecPath("feat/")).toThrow();
+  });
+});
+
+describe("path helpers", () => {
+  test("getCcqaDir uses process.cwd by default", () => {
+    expect(getCcqaDir()).toBe(`${process.cwd()}/.ccqa`);
+  });
+
+  test("getCcqaDir uses provided cwd", () => {
+    expect(getCcqaDir("/custom")).toBe("/custom/.ccqa");
+  });
+
+  test("getFeatureDir returns correct path", () => {
+    expect(getFeatureDir("my-feature", "/custom")).toBe("/custom/.ccqa/features/my-feature");
+  });
+
+  test("getSpecDir returns correct path", () => {
+    expect(getSpecDir("my-feature", "my-spec", "/custom")).toBe(
+      "/custom/.ccqa/features/my-feature/test-cases/my-spec",
+    );
+  });
+
+
+});
+
+describe("routeToMarkdown", () => {
+  const baseRoute: Route = {
+    specName: "create-and-complete",
+    timestamp: "2026-03-28T00:00:00.000Z",
+    status: "passed",
+    steps: [],
+  };
+
+  test("generates correct frontmatter", () => {
+    const md = routeToMarkdown(baseRoute);
+    expect(md).toContain('specName: "create-and-complete"');
+    expect(md).toContain('timestamp: "2026-03-28T00:00:00.000Z"');
+    expect(md).toContain('status: "passed"');
+  });
+
+  test("generates step section", () => {
+    const route: Route = {
+      ...baseRoute,
+      steps: [
+        { title: "Login", action: "filled form", observation: "redirected", status: "PASSED" },
+      ],
+    };
+    const md = routeToMarkdown(route);
+    expect(md).toContain("## Login");
+    expect(md).toContain("- **action**: filled form");
+    expect(md).toContain("- **observation**: redirected");
+    expect(md).toContain("- **status**: PASSED");
+  });
+
+  test("includes reason when present", () => {
+    const route: Route = {
+      ...baseRoute,
+      steps: [
+        { title: "Fail", action: "clicked", observation: "nothing", status: "FAILED", reason: "button disabled" },
+      ],
+    };
+    const md = routeToMarkdown(route);
+    expect(md).toContain("- **reason**: button disabled");
+  });
+
+  test("omits reason line when absent", () => {
+    const route: Route = {
+      ...baseRoute,
+      steps: [
+        { title: "Pass", action: "clicked", observation: "ok", status: "PASSED" },
+      ],
+    };
+    const md = routeToMarkdown(route);
+    expect(md).not.toContain("- **reason**");
+  });
+});

package/src/store/index.ts

@@ -0,0 +1,193 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Route, TraceAction } from "../types.ts";
+
+const CCQA_DIR = ".ccqa";
+
+export function getCcqaDir(cwd: string = process.cwd()): string {
+  return join(cwd, CCQA_DIR);
+}
+
+// "tasks/create-and-complete" → { featureName: "tasks", specName: "create-and-complete" }
+export function parseSpecPath(specPath: string): { featureName: string; specName: string } {
+  const parts = specPath.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(`Invalid spec path: "${specPath}". Expected format: "<feature>/<spec>"`);
+  }
+  return { featureName: parts[0], specName: parts[1] };
+}
+
+export function getFeatureDir(featureName: string, cwd?: string): string {
+  return join(getCcqaDir(cwd), "features", featureName);
+}
+
+export function getSpecDir(featureName: string, specName: string, cwd?: string): string {
+  return join(getFeatureDir(featureName, cwd), "test-cases", specName);
+}
+
+
+export async function ensureCcqaDir(cwd?: string): Promise<void> {
+  await mkdir(join(getCcqaDir(cwd), "features"), { recursive: true });
+}
+
+
+export async function readSpecFile(featureName: string, specName: string, cwd?: string): Promise<string> {
+  const specPath = join(getSpecDir(featureName, specName, cwd), "test-spec.md");
+  return readFile(specPath, "utf-8").catch(() => {
+    throw new Error(`Spec file not found: ${specPath}`);
+  });
+}
+
+export async function saveRoute(featureName: string, specName: string, route: Route, cwd?: string): Promise<string> {
+  const specDir = getSpecDir(featureName, specName, cwd);
+  await mkdir(specDir, { recursive: true });
+  const routePath = join(specDir, "route.md");
+  await writeFile(routePath, routeToMarkdown(route), "utf-8");
+  return routePath;
+}
+
+export async function saveTraceActions(
+  featureName: string,
+  specName: string,
+  actions: TraceAction[],
+  cwd?: string,
+): Promise<string> {
+  const specDir = getSpecDir(featureName, specName, cwd);
+  await mkdir(specDir, { recursive: true });
+  const actionsPath = join(specDir, "actions.json");
+  await writeFile(actionsPath, JSON.stringify(actions, null, 2), "utf-8");
+  return actionsPath;
+}
+
+// --- Setup (shared procedures) ---
+
+export function getSetupDir(name: string, cwd?: string): string {
+  return join(getCcqaDir(cwd), "setups", name);
+}
+
+export async function readSetupSpecFile(name: string, cwd?: string): Promise<string> {
+  const specPath = join(getSetupDir(name, cwd), "setup-spec.md");
+  return readFile(specPath, "utf-8").catch(() => {
+    throw new Error(`Setup spec not found: ${specPath}`);
+  });
+}
+
+export async function saveSetupActions(name: string, actions: TraceAction[], cwd?: string): Promise<string> {
+  const dir = getSetupDir(name, cwd);
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, "actions.json");
+  await writeFile(path, JSON.stringify(actions, null, 2), "utf-8");
+  return path;
+}
+
+export async function getSetupActions(name: string, cwd?: string): Promise<{ path: string; actions: TraceAction[] }> {
+  const path = join(getSetupDir(name, cwd), "actions.json");
+  const content = await readFile(path, "utf-8").catch(() => {
+    throw new Error(`No setup actions found for: ${name}. Run \`ccqa trace-setup ${name}\` first.`);
+  });
+  return { path, actions: JSON.parse(content) as TraceAction[] };
+}
+
+export async function saveSetupRoute(name: string, route: Route, cwd?: string): Promise<string> {
+  const dir = getSetupDir(name, cwd);
+  await mkdir(dir, { recursive: true });
+  const routePath = join(dir, "route.md");
+  await writeFile(routePath, routeToMarkdown(route), "utf-8");
+  return routePath;
+}
+
+export async function saveSetupTestScript(name: string, content: string, cwd?: string): Promise<string> {
+  const dir = getSetupDir(name, cwd);
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, "test.spec.ts");
+  await writeFile(path, content, "utf-8");
+  return path;
+}
+
+export async function removeSetupTestScript(name: string, cwd?: string): Promise<void> {
+  const path = join(getSetupDir(name, cwd), "test.spec.ts");
+  const { unlink } = await import("node:fs/promises");
+  await unlink(path).catch(() => {});
+}
+
+// --- Trace Actions ---
+
+export async function getTraceActions(
+  featureName: string,
+  specName: string,
+  cwd?: string,
+): Promise<{ path: string; actions: TraceAction[] }> {
+  const path = join(getSpecDir(featureName, specName, cwd), "actions.json");
+  const content = await readFile(path, "utf-8").catch(() => {
+    throw new Error(`No trace actions found for spec: ${featureName}/${specName}. Run \`ccqa trace\` first.`);
+  });
+  return { path, actions: JSON.parse(content) as TraceAction[] };
+}
+
+export async function saveTestScript(
+  featureName: string,
+  specName: string,
+  content: string,
+  cwd?: string,
+): Promise<string> {
+  const specDir = getSpecDir(featureName, specName, cwd);
+  await mkdir(specDir, { recursive: true });
+  const scriptPath = join(specDir, "test.spec.ts");
+  await writeFile(scriptPath, content, "utf-8");
+  return scriptPath;
+}
+
+export async function getTestScript(featureName: string, specName: string, cwd?: string): Promise<string | null> {
+  const path = join(getSpecDir(featureName, specName, cwd), "test.spec.ts");
+  return stat(path).then(() => path).catch(() => null);
+}
+
+export async function listAllSpecs(cwd?: string): Promise<Array<{ featureName: string; specName: string }>> {
+  const featuresDir = join(getCcqaDir(cwd), "features");
+  const featureDirs = await readdir(featuresDir).catch(() => []);
+
+  const perFeature = await Promise.all(
+    featureDirs.map(async (featureName) => {
+      const testCasesDir = join(featuresDir, featureName, "test-cases");
+      const specDirs = await readdir(testCasesDir).catch(() => []);
+      const entries = await Promise.all(
+        specDirs.map(async (specName) => {
+          const scriptFile = join(testCasesDir, specName, "test.spec.ts");
+          const exists = await stat(scriptFile).then(() => true).catch(() => false);
+          return exists ? { featureName, specName } : null;
+        }),
+      );
+      return entries.filter((e): e is { featureName: string; specName: string } => e !== null);
+    }),
+  );
+
+  return perFeature.flat();
+}
+
+export async function listSpecsForFeature(featureName: string, cwd?: string): Promise<string[]> {
+  const testCasesDir = join(getFeatureDir(featureName, cwd), "test-cases");
+  return readdir(testCasesDir).catch(() => []);
+}
+
+
+export function routeToMarkdown(route: Route): string {
+  const lines: string[] = [
+    "---",
+    `specName: "${route.specName}"`,
+    `timestamp: "${route.timestamp}"`,
+    `status: "${route.status}"`,
+    "---",
+    "",
+  ];
+
+  for (const step of route.steps) {
+    lines.push(`## ${step.title}`);
+    lines.push(`- **action**: ${step.action}`);
+    lines.push(`- **observation**: ${step.observation}`);
+    lines.push(`- **status**: ${step.status}`);
+    if (step.reason) lines.push(`- **reason**: ${step.reason}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/types.test.ts

@@ -0,0 +1,96 @@
+import { describe, test, expect } from "bun:test";
+import { TestStepSchema, TestSpecSchema, RouteStepSchema, RouteSchema } from "./types.ts";
+
+describe("TestStepSchema", () => {
+  test("accepts valid step data", () => {
+    const result = TestStepSchema.safeParse({
+      id: "step-01",
+      title: "Login",
+      instruction: "Go to login page",
+      expected: "Login form is visible",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects missing required fields", () => {
+    expect(TestStepSchema.safeParse({ id: "step-01" }).success).toBe(false);
+  });
+});
+
+describe("TestSpecSchema", () => {
+  test("accepts valid spec with optional prerequisites absent", () => {
+    const result = TestSpecSchema.safeParse({
+      title: "My Test",
+      baseUrl: "http://localhost:3000",
+      steps: [],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts valid spec with prerequisites", () => {
+    const result = TestSpecSchema.safeParse({
+      title: "My Test",
+      baseUrl: "http://localhost:3000",
+      prerequisites: "Must be logged in",
+      steps: [],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects missing title", () => {
+    expect(
+      TestSpecSchema.safeParse({ baseUrl: "http://localhost", steps: [] }).success,
+    ).toBe(false);
+  });
+});
+
+describe("RouteStepSchema", () => {
+  test("accepts valid PASSED status", () => {
+    const result = RouteStepSchema.safeParse({
+      title: "Login",
+      action: "filled form",
+      observation: "redirected",
+      status: "PASSED",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts FAILED and SKIPPED status", () => {
+    const base = { title: "t", action: "a", observation: "o" };
+    expect(RouteStepSchema.safeParse({ ...base, status: "FAILED" }).success).toBe(true);
+    expect(RouteStepSchema.safeParse({ ...base, status: "SKIPPED" }).success).toBe(true);
+  });
+
+  test("rejects invalid status", () => {
+    const result = RouteStepSchema.safeParse({
+      title: "t", action: "a", observation: "o", status: "UNKNOWN",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("reason field is optional", () => {
+    const withReason = RouteStepSchema.safeParse({
+      title: "t", action: "a", observation: "o", status: "FAILED", reason: "bug",
+    });
+    const withoutReason = RouteStepSchema.safeParse({
+      title: "t", action: "a", observation: "o", status: "PASSED",
+    });
+    expect(withReason.success).toBe(true);
+    expect(withoutReason.success).toBe(true);
+  });
+});
+
+describe("RouteSchema", () => {
+  test("accepts valid passed/failed status", () => {
+    const base = { specName: "check", timestamp: "2026-01-01T00:00:00Z", steps: [] };
+    expect(RouteSchema.safeParse({ ...base, status: "passed" }).success).toBe(true);
+    expect(RouteSchema.safeParse({ ...base, status: "failed" }).success).toBe(true);
+  });
+
+  test("rejects invalid status", () => {
+    const result = RouteSchema.safeParse({
+      specName: "check", timestamp: "2026-01-01T00:00:00Z", status: "PASSED", steps: [],
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/types.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+
+export const TestStepSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  instruction: z.string(),
+  expected: z.string(),
+});
+export type TestStep = z.infer<typeof TestStepSchema>;
+
+export const SetupRefSchema = z.object({
+  name: z.string(),
+  params: z.record(z.string(), z.string()).optional(),
+});
+export type SetupRef = z.infer<typeof SetupRefSchema>;
+
+export const TestSpecSchema = z.object({
+  title: z.string(),
+  baseUrl: z.string(),
+  prerequisites: z.string().optional(),
+  setups: z.array(SetupRefSchema).optional(),
+  steps: z.array(TestStepSchema),
+});
+export type TestSpec = z.infer<typeof TestSpecSchema>;
+
+export const PlaceholderDefSchema = z.object({
+  dummy: z.string(),
+  description: z.string().optional(),
+});
+
+export const SetupSpecSchema = z.object({
+  title: z.string(),
+  placeholders: z.record(z.string(), PlaceholderDefSchema).optional(),
+  steps: z.array(TestStepSchema),
+});
+export type SetupSpec = z.infer<typeof SetupSpecSchema>;
+
+export const RouteStepSchema = z.object({
+  title: z.string(),
+  action: z.string(),
+  observation: z.string(),
+  status: z.enum(["PASSED", "FAILED", "SKIPPED"]),
+  reason: z.string().optional(),
+});
+export type RouteStep = z.infer<typeof RouteStepSchema>;
+
+export const RouteSchema = z.object({
+  specName: z.string(),
+  timestamp: z.string(),
+  status: z.enum(["passed", "failed"]),
+  steps: z.array(RouteStepSchema),
+});
+export type Route = z.infer<typeof RouteSchema>;
+
+
+export type TraceCommand =
+  | "cookies_clear"
+  | "open" | "click" | "dblclick" | "fill" | "type"
+  | "check" | "uncheck" | "press" | "select"
+  | "hover" | "scroll" | "drag" | "wait" | "snapshot"
+  | "assert";
+
+export type AssertType =
+  | "text_visible" | "text_not_visible"
+  | "element_visible" | "element_not_visible"
+  | "url_contains"
+  | "element_enabled" | "element_disabled"
+  | "element_checked" | "element_unchecked";
+
+export interface TraceAction {
+  command: TraceCommand;
+  selector?: string;
+  label?: string;
+  value?: string;
+  /** For drag: destination selector */
+  target?: string;
+  /** For scroll: direction (up/down/left/right) and optional pixels */
+  direction?: string;
+  pixels?: string;
+  observation?: string;
+  /** Only for command: "assert" */
+  assertType?: AssertType;
+}
+
+export type StepStatus = "STEP_START" | "STEP_DONE" | "ASSERTION_FAILED" | "STEP_SKIPPED" | "RUN_COMPLETED";
+
+export interface ParsedStatusLine {
+  type: StepStatus;
+  stepId: string;
+  detail: string;
+}