@roubo/shared 0.1.0

package/testbench-canonicalize.ts

@@ -0,0 +1,129 @@
+// Pure canonicalisation of a TestCasesPlan into a deterministic string
+// (spike-407 AC1 rules 1-5). The server hashes this string with node:crypto to
+// detect staleness (FR-016); this module does NOT hash.
+//
+// Platform-agnostic: no fs, no node:crypto, no React. Safe in the Vite client
+// build. Canonical contract types land with testbench-contracts (#6); until
+// then this consumes the local types in testbench-domain-types.ts.
+//
+// See .specifications/testbench/spikes/spike-407-staleness-hash-reconcile.md
+// AC1 (the rules) and AC2 (the worked example this module is verified against).
+
+import type { Case, Observation, Step, TestCasesPlan } from "./testbench-domain-types";
+
+// Byte-wise (code-point) comparison, NOT a locale collator. A locale-aware
+// collator is environment-dependent and would make the canonical string (and
+// therefore the hash) non-deterministic across machines. Comparing the raw
+// UTF-16 code units of two strings is a total, stable, environment-independent
+// order, which is what spike-407 AC1 rule 2 requires.
+function compareCodePoints(a: string, b: string): number {
+  if (a < b) {
+    return -1;
+  }
+  if (a > b) {
+    return 1;
+  }
+  return 0;
+}
+
+// String content-normalisation (spike-407 AC1 rule 3), applied to every
+// included string value: NFC normalise, convert CRLF and lone CR to LF, trim
+// leading/trailing whitespace, collapse each run of internal whitespace
+// (spaces/tabs/newlines) to a single space.
+function normalizeString(value: string): string {
+  return value.normalize("NFC").replace(/\r\n?/g, "\n").trim().replace(/\s+/g, " ");
+}
+
+// Per-observation projection in fixed canonical key order: id, expected.
+function projectObservation(observation: Observation): { id: string; expected: string } {
+  return {
+    id: observation.id,
+    expected: normalizeString(observation.expected),
+  };
+}
+
+// Per-step projection in fixed canonical key order: id, instruction,
+// observations (sorted by Observation.id).
+function projectStep(step: Step): {
+  id: string;
+  instruction: string;
+  observations: ReturnType<typeof projectObservation>[];
+} {
+  const observations = [...step.observations]
+    .sort((a, b) => compareCodePoints(a.id, b.id))
+    .map(projectObservation);
+  return {
+    id: step.id,
+    instruction: normalizeString(step.instruction),
+    observations,
+  };
+}
+
+// Per-case projection in fixed canonical key order: id, title, level, priority
+// (when present), preconditions (when present and non-empty), steps (sorted by
+// Step.id).
+//
+// `level` is an integer in the merged v1.1.0 shape; it is stringified before
+// normalisation so the canonical form stays an all-strings projection. `priority`
+// is optional in v1.1.0 (canonical authors omit it): an absent priority omits the
+// key, exactly as preconditions does. The canonical product-dev metadata fields
+// (area, type, tags, linked_*) are deliberately NOT projected: the staleness hash
+// tracks the testable body (title, level, steps), so re-tagging or re-linking a
+// case never marks it stale-for-retest. Like every TargetingField and unknown
+// field, they are dropped.
+//
+// preconditions order is PRESERVED (not sorted). An absent and an empty
+// preconditions list canonicalise identically: the key is omitted in both cases.
+function projectCase(testCase: Case): Record<string, unknown> {
+  const projected: Record<string, unknown> = {
+    id: testCase.id,
+    title: normalizeString(testCase.title),
+    level: normalizeString(String(testCase.level)),
+  };
+
+  if (testCase.priority !== undefined) {
+    projected.priority = normalizeString(testCase.priority);
+  }
+
+  if (testCase.preconditions !== undefined && testCase.preconditions.length > 0) {
+    projected.preconditions = testCase.preconditions.map(normalizeString);
+  }
+
+  projected.steps = [...testCase.steps]
+    .sort((a, b) => compareCodePoints(a.id, b.id))
+    .map(projectStep);
+
+  return projected;
+}
+
+// Produce the deterministic canonical string for a SINGLE case (spike-407 AC1,
+// the per-case projection). This is the per-case unit that `canonicalize(plan)`
+// composes over the whole case set, exported so `testbench-domain.reconcile`
+// can compare one plan case's canonical body against the snapshot stored on a
+// recorded result, sharing one canonicalisation authority (no second copy of
+// the projection rules). Applies the same projection + normalisation + fixed
+// key order as the plan-level canonicalize: drops every TargetingField and
+// unknown field, sorts steps/observations by id, preserves preconditions order.
+export function canonicalizeCase(testCase: Case): string {
+  return JSON.stringify(projectCase(testCase));
+}
+
+// Produce the deterministic canonical string for a plan (spike-407 AC1).
+//
+// Rules, in order:
+//   1. Project to included fields only (drop $schema, schemaVersion, specSlug,
+//      every TargetingField, and any unknown field).
+//   2. Stable-id sort cases/steps/observations by code-point comparison;
+//      preconditions order preserved.
+//   3. Normalise every included string value.
+//   4. Serialise with fixed canonical key order and no insignificant whitespace.
+//   5. Return the string (no hashing).
+//
+// The empty case set canonicalises to a fixed, stable, non-empty string:
+//   {"cases":[]}
+export function canonicalize(plan: TestCasesPlan): string {
+  const cases = [...plan.cases].sort((a, b) => compareCodePoints(a.id, b.id)).map(projectCase);
+  // JSON.stringify with no spacing emits keys in insertion order (the fixed
+  // canonical order built above) and no insignificant whitespace.
+  return JSON.stringify({ cases });
+}

package/testbench-contracts.ts

@@ -0,0 +1,271 @@
+// TestBench contracts: the single, compile-time source of truth (in `shared/`)
+// for the two published, versioned TestBench files, `test-cases.json` and
+// `test-results.json`. Both server and client validate against these schemas
+// (FR-019, FR-020, FR-021). Shapes follow the architecture.md Data model table
+// exactly; the runtime validators wrap `safeParse` (never throw) and return
+// actionable, field-named errors.
+//
+// Scope note: this module authors the zod source schemas, the inferred types,
+// the runtime validators, and the versioned `$id` constants. The roots carry
+// `.meta({ $id })` so the generate script + CI drift guard (FR-023, #411) can
+// emit versioned JSON Schema from them; the store IO (#11) is out of scope here.
+
+import { z } from "zod";
+
+// ── Versioned schema identifiers (NFR-005) ──
+//
+// Each published file carries a `$schema` URI whose path embeds a semver. A
+// breaking change ships a major bump plus a migration registry entry; additive
+// optional fields (like the reserved targeting fields below) do not bump the
+// version. `TEST_CASES_SCHEMA_VERSION` / `TEST_RESULTS_SCHEMA_VERSION` are the
+// matching `schemaVersion` string values kept consistent with the `$id` semver.
+
+export const TEST_CASES_SCHEMA_ID = "https://roubo.dev/schema/testbench/test-cases/v1.1.0.json";
+export const TEST_CASES_SCHEMA_VERSION = "1.1.0";
+
+export const TEST_RESULTS_SCHEMA_ID = "https://roubo.dev/schema/testbench/test-results/v2.0.0.json";
+export const TEST_RESULTS_SCHEMA_VERSION = "2.0.0";
+
+// ── Shared leaf schemas ──
+
+// The fixed derived-status set (FR-009). Owned by `testbench-domain` as a
+// concept, but the literal enum lives here so both files can reference it.
+export const CaseStatusSchema = z.enum([
+  "not_started",
+  "in_progress",
+  "passed",
+  "failed",
+  "blocked",
+]);
+export type CaseStatus = z.infer<typeof CaseStatusSchema>;
+
+// Author of a mark, override, or note (FR-012). `isSentinel` is set when git
+// identity was unset at write time, so writes never fail on missing identity.
+export const AuthorSchema = z
+  .object({
+    name: z.string(),
+    email: z.string(),
+    isSentinel: z.literal(true).optional(),
+  })
+  .strict();
+export type Author = z.infer<typeof AuthorSchema>;
+
+// Reserved, optional, additive targeting field (FR-019, NFR-005). Flat and
+// all-optional: ignored by the in-app UI today, reserved for the future
+// guided-execution Chrome extension. Present or absent, both validate; adding
+// it to a step/observation is non-breaking.
+export const TargetingFieldSchema = z
+  .object({
+    cssSelector: z.string().optional(),
+    ariaRole: z.string().optional(),
+    ariaName: z.string().optional(),
+    textAnchor: z.string().optional(),
+    routeContext: z.string().optional(),
+    region: z.string().optional(),
+  })
+  .strict();
+export type TargetingField = z.infer<typeof TargetingFieldSchema>;
+
+// ── test-cases.json (the source plan; never mutated) ──
+
+export const ObservationSchema = z
+  .object({
+    id: z.string(),
+    expected: z.string(),
+    // Reserved per-observation targeting field (FR-019).
+    observe: TargetingFieldSchema.optional(),
+  })
+  .strict();
+export type Observation = z.infer<typeof ObservationSchema>;
+
+export const StepSchema = z
+  .object({
+    id: z.string(),
+    instruction: z.string(),
+    observations: z.array(ObservationSchema),
+    // Reserved per-step targeting field (FR-019).
+    target: TargetingFieldSchema.optional(),
+  })
+  .strict();
+export type Step = z.infer<typeof StepSchema>;
+
+// Recommended `type` vocabulary: the canonical product-dev set
+// (functional, security, performance, accessibility, integration, negative,
+// edge_case, e2e_flow) expanded with `reliability` and `structural`, both
+// already in use across real specs. This is authoring guidance carried in the
+// product-dev docs; the contract itself validates `type` as a permissive string
+// (see CaseSchema), never a strict enum. The merged schema (v1.1.0) is strict on
+// STRUCTURE (envelope, step ids, required fields) but lenient on open-ended
+// metadata, so a newly-coined `type` can never silently make an entire spec
+// undiscoverable (the failure mode v1.1.0 fixed).
+export const RECOMMENDED_CASE_TYPES = [
+  "functional",
+  "security",
+  "performance",
+  "accessibility",
+  "integration",
+  "negative",
+  "edge_case",
+  "e2e_flow",
+  "reliability",
+  "structural",
+] as const;
+
+export const CaseSchema = z
+  .object({
+    id: z.string(),
+    title: z.string(),
+    // Canonical feature area (kebab-case), e.g. "checkout". Required.
+    area: z.string(),
+    // Canonical level: an integer 1-4 (L1 smoke .. L4 exploratory). The merge
+    // keeps level from the canonical product-dev format (an integer), replacing
+    // the earlier string level.
+    level: z.number().int().min(1).max(4),
+    // Test flavor (see RECOMMENDED_CASE_TYPES). Permissive string by design.
+    type: z.string().min(1),
+    // Optional priority label (carried from the TestBench shape). Canonical
+    // authors omit it; the UI rollup buckets cases with no priority gracefully.
+    priority: z.string().optional(),
+    preconditions: z.array(z.string()).optional(),
+    steps: z.array(StepSchema),
+    // Canonical metadata: free-form tags + requirement/story traceability.
+    // Every case links at least one requirement; user-story links may be empty.
+    tags: z.array(z.string()),
+    linked_requirement_ids: z.array(z.string()).min(1),
+    linked_user_story_ids: z.array(z.string()),
+  })
+  .strict();
+export type Case = z.infer<typeof CaseSchema>;
+
+export const TestCasesPlanSchema = z
+  .object({
+    $schema: z.string(),
+    schemaVersion: z.string(),
+    specSlug: z.string(),
+    cases: z.array(CaseSchema),
+  })
+  .strict()
+  // Pass the literal `$id` key through `.meta()` so `z.toJSONSchema()` emits a
+  // top-level `$id` carrying the versioned identifier (NFR-005). The generate
+  // script + CI drift guard (FR-023) consume this.
+  .meta({ $id: TEST_CASES_SCHEMA_ID });
+export type TestCasesPlan = z.infer<typeof TestCasesPlanSchema>;
+
+// ── test-results.json (the sidecar; references cases by stable id) ──
+
+export const ObservationMarkSchema = z
+  .object({
+    result: z.enum(["pass", "fail"]),
+    author: AuthorSchema,
+    timestamp: z.string(),
+  })
+  .strict();
+export type ObservationMark = z.infer<typeof ObservationMarkSchema>;
+
+// Recorded distinctly from `derivedStatus` (FR-010).
+export const StatusOverrideSchema = z
+  .object({
+    status: CaseStatusSchema,
+    author: AuthorSchema,
+    timestamp: z.string(),
+  })
+  .strict();
+export type StatusOverride = z.infer<typeof StatusOverrideSchema>;
+
+// Append-only: no edit/delete path exists (FR-011). `statusAtWrite` captures
+// the effective status at the moment the note was written.
+export const NoteSchema = z
+  .object({
+    id: z.string(),
+    text: z.string(),
+    author: AuthorSchema,
+    timestamp: z.string(),
+    statusAtWrite: CaseStatusSchema,
+  })
+  .strict();
+export type Note = z.infer<typeof NoteSchema>;
+
+export const CaseResultSchema = z
+  .object({
+    // Keyed by observation id; results reference cases by stable id and never
+    // require editing test-cases.json (FR-020).
+    observationMarks: z.record(z.string(), ObservationMarkSchema),
+    derivedStatus: CaseStatusSchema,
+    statusOverride: StatusOverrideSchema.optional(),
+    notes: z.array(NoteSchema),
+    // A removed case's result is marked orphaned and retained, never deleted,
+    // and excluded from the rollup (FR-013, FR-017).
+    orphaned: z.literal(true).optional(),
+    // The per-case canonical body snapshot reconcile compares against the live
+    // plan to classify changed vs unchanged (#413, spike-407 AC3). Optional so a
+    // result with no stored snapshot still parses and is conservatively
+    // classified changed; persisting it lets the signal survive a round-trip to
+    // disk (#447).
+    caseCanon: z.string().optional(),
+  })
+  .strict();
+export type CaseResult = z.infer<typeof CaseResultSchema>;
+
+// The recorded-results body for a single spec: case results keyed by case id,
+// plus a write timestamp. As of the v2.0.0 flatten (#493), one results file
+// lives per worktree (sibling of test-cases.json), so there is exactly one of
+// these per file and it sits at the top level. This stays a named type because
+// it is also the API result shape the client reads (the route projects the file
+// body down to it), so keeping the name avoids client churn.
+export const BenchResultsSchema = z
+  .object({
+    // Keyed by case id.
+    caseResults: z.record(z.string(), CaseResultSchema),
+    updatedAt: z.string(),
+  })
+  .strict();
+export type BenchResults = z.infer<typeof BenchResultsSchema>;
+
+export const TestResultsFileSchema = z
+  .object({
+    $schema: z.string(),
+    schemaVersion: z.string(),
+    planHash: z.string(),
+    // Flattened in v2.0.0 (#493): one results file per worktree means exactly
+    // one bench per file, so case results sit at the top level rather than
+    // nested under a per-bench `benches` map. Keyed by case id.
+    caseResults: z.record(z.string(), CaseResultSchema),
+    updatedAt: z.string(),
+  })
+  .strict()
+  // Pass the literal `$id` key through `.meta()` so `z.toJSONSchema()` emits a
+  // top-level `$id` carrying the versioned identifier (NFR-005). The generate
+  // script + CI drift guard (FR-023) consume this.
+  .meta({ $id: TEST_RESULTS_SCHEMA_ID });
+export type TestResultsFile = z.infer<typeof TestResultsFileSchema>;
+
+// ── Runtime validators ──
+//
+// Both wrap `safeParse` (never throw, FR-021) and return a discriminated result.
+// On failure, each zod issue becomes a clear `path: message` string keyed by
+// the field that failed.
+
+export type ValidationResult<T> = { ok: true; data: T } | { ok: false; errors: string[] };
+
+function zodIssuesToFieldErrors(issues: z.ZodIssue[]): string[] {
+  return issues.map((issue) => {
+    const path = issue.path.join(".");
+    return path ? `${path}: ${issue.message}` : issue.message;
+  });
+}
+
+export function validateTestCases(raw: unknown): ValidationResult<TestCasesPlan> {
+  const parsed = TestCasesPlanSchema.safeParse(raw);
+  if (!parsed.success) {
+    return { ok: false, errors: zodIssuesToFieldErrors(parsed.error.issues) };
+  }
+  return { ok: true, data: parsed.data };
+}
+
+export function validateTestResults(raw: unknown): ValidationResult<TestResultsFile> {
+  const parsed = TestResultsFileSchema.safeParse(raw);
+  if (!parsed.success) {
+    return { ok: false, errors: zodIssuesToFieldErrors(parsed.error.issues) };
+  }
+  return { ok: true, data: parsed.data };
+}

package/testbench-domain-types.ts

@@ -0,0 +1,128 @@
+// Minimal, self-contained input types for the pure TestBench domain modules
+// (testbench-domain, testbench-canonicalize).
+//
+// The canonical contract types are owned by testbench-contracts (issue #6),
+// which is authored in parallel with this work (#412) and has NOT landed yet.
+// To keep these pure modules self-contained, the shapes below are local copies
+// that structurally match the architecture.md data model
+// (.specifications/testbench/architecture.md, the Data model table). When #6
+// lands, it owns the canonical zod-derived types and these local interfaces
+// should be aligned with (or replaced by) the ones it exports.
+//
+// These modules are platform-agnostic: no fs, no node:crypto, no React. They
+// must not break the Vite client build.
+
+// The fixed status set (FR-009). "blocked" is NOT derivable from observation
+// marks (marks are pass|fail only); it reaches a CaseResult only through an
+// explicit override (FR-010), via effectiveStatus = override ?? derived.
+export type CaseStatus = "not_started" | "in_progress" | "passed" | "failed" | "blocked";
+
+// Author of a mark or note (FR-012). Included for structural fidelity with the
+// architecture.md shape; the domain functions do not read it.
+export interface Author {
+  name: string;
+  email: string;
+  isSentinel?: true;
+}
+
+// A single observation result keyed by observation id in a CaseResult's
+// observationMarks map. Marks are pass|fail only.
+export interface ObservationMark {
+  result: "pass" | "fail";
+  author: Author;
+  timestamp: string;
+}
+
+// Reserved, all-optional guided-execution targeting field (FR-019). Ignored by
+// canonicalisation (see testbench-canonicalize): present on the input shape so
+// these local types match the architecture.md Step/Observation shapes.
+export interface TargetingField {
+  cssSelector?: string;
+  ariaRole?: string;
+  ariaName?: string;
+  textAnchor?: string;
+  routeContext?: string;
+  region?: string;
+}
+
+export interface Observation {
+  id: string;
+  expected: string;
+  observe?: TargetingField;
+}
+
+export interface Step {
+  id: string;
+  instruction: string;
+  observations: Observation[];
+  target?: TargetingField;
+}
+
+// Mirrors the merged v1.1.0 CaseSchema in testbench-contracts.ts: the canonical
+// product-dev fields (area, integer level, type, tags, linked_*) unioned with
+// the TestBench shape (optional priority, TestBench step shape). The pure domain
+// modules only read id/title/level/priority/preconditions/steps; the canonical
+// metadata fields ride along for structural fidelity with the contract type.
+export interface Case {
+  id: string;
+  title: string;
+  area: string;
+  level: number;
+  type: string;
+  priority?: string;
+  preconditions?: string[];
+  steps: Step[];
+  tags: string[];
+  linked_requirement_ids: string[];
+  linked_user_story_ids: string[];
+}
+
+export interface TestCasesPlan {
+  $schema: string;
+  schemaVersion: string;
+  specSlug: string;
+  cases: Case[];
+}
+
+// ── Result-side input shapes (consumed by testbench-domain.reconcile) ──
+//
+// These mirror the architecture.md data model and the canonical zod shapes in
+// testbench-contracts.ts (NoteSchema, StatusOverrideSchema, CaseResultSchema,
+// BenchResultsSchema). They are local copies for the same reason as the shapes
+// above: testbench-contracts owns the canonical types, and these should be
+// aligned with (or replaced by) its exports when this module consolidates.
+
+// An explicit status override, recorded distinctly from derivedStatus (FR-010).
+export interface StatusOverride {
+  status: CaseStatus;
+  author: Author;
+  timestamp: string;
+}
+
+// An append-only note (FR-011). statusAtWrite captures the effective status at
+// the moment the note was written.
+export interface Note {
+  id: string;
+  text: string;
+  author: Author;
+  timestamp: string;
+  statusAtWrite: CaseStatus;
+}
+
+// A recorded result for one case, keyed by case id in BenchResults.caseResults.
+//
+// The shape is now derived from the published contract's CaseResultSchema
+// (testbench-contracts), re-exported here so it is declared once. This is a
+// type-only re-export: it is erased at compile time, so no zod runtime import
+// is pulled into these pure, Vite-safe domain modules. caseCanon (the per-case
+// canonical body snapshot reconcile compares against the live plan to classify
+// changed vs unchanged) is one of the contract fields; a result with no stored
+// snapshot is conservatively classified changed.
+import type { CaseResult } from "./testbench-contracts";
+export type { CaseResult };
+
+// One bench's recorded results, keyed by case id.
+export interface BenchResults {
+  caseResults: Record<string, CaseResult>;
+  updatedAt: string;
+}