✅ Add directive system for snippet test control

Implement comprehensive directive system for controlling snippet behavior
via HTML comment annotations in markdown.

Control directives (skip, description, timeout), assertion directives
(expect-error, expect-output, expect-return, etc.), and transformation
directives (await, return-statement) enable flexible test configuration
directly in documentation.

Author: elbywan

test/snippets/directives/await.ts

@@ -0,0 +1,19 @@
+/**
+ * await directive - wraps code in async IIFE
+ */
+
+import type { TransformDirective } from "./types.js"
+
+export const awaitDirective: TransformDirective = {
+  type: "transform",
+  name: "await",
+  description: "Automatically wrap code in an async IIFE for top-level await",
+  handler: (snippet, _directive) => {
+    // Mark that this snippet needs async wrapping
+    // The actual transformation happens in the transformer module
+    return {
+      code: snippet.code,
+      modified: false // Transformation will be done by transformer
+    }
+  }
+}

test/snippets/directives/description.ts

@@ -0,0 +1,14 @@
+/**
+ * description directive
+ */
+
+import type { ControlDirective } from "./types.js"
+
+export const description: ControlDirective = {
+  type: "control",
+  name: "description",
+  handler: () => {
+    // Description is purely for documentation, doesn't affect execution
+    return null
+  }
+}

test/snippets/directives/expectError.ts

@@ -0,0 +1,32 @@
+/**
+ * expect-error directive
+ */
+
+import type { AssertionDirective } from "./types.js"
+
+export const expectError: AssertionDirective = {
+  type: "assertion",
+  name: "expect-error",
+  handler: (executionResult, directive) => {
+    if (!executionResult.error) {
+      return {
+        passed: false,
+        message: "Expected snippet to throw an error, but it succeeded",
+      }
+    }
+
+    if (typeof directive.args === "string") {
+      const expectedMessage = directive.args
+      if (!executionResult.error.message.includes(expectedMessage)) {
+        return {
+          passed: false,
+          message: `Expected error message to include "${expectedMessage}"`,
+          expected: expectedMessage,
+          actual: executionResult.error.message,
+        }
+      }
+    }
+
+    return { passed: true }
+  }
+}

test/snippets/directives/expectNoError.ts

@@ -0,0 +1,21 @@
+/**
+ * expect-no-error directive
+ */
+
+import type { AssertionDirective } from "./types.js"
+
+export const expectNoError: AssertionDirective = {
+  type: "assertion",
+  name: "expect-no-error",
+  handler: executionResult => {
+    if (executionResult.error) {
+      return {
+        passed: false,
+        message: "Expected snippet to succeed, but it threw an error",
+        actual: executionResult.error.message,
+      }
+    }
+
+    return { passed: true }
+  }
+}

test/snippets/directives/expectOutput.ts

@@ -0,0 +1,25 @@
+/**
+ * expect-output directive
+ */
+
+import type { AssertionDirective } from "./types.js"
+
+export const expectOutput: AssertionDirective = {
+  type: "assertion",
+  name: "expect-output",
+  handler: (executionResult, directive) => {
+    const output = executionResult.logs.join("\n")
+    const expected = String(directive.args)
+
+    if (!output.includes(expected)) {
+      return {
+        passed: false,
+        message: `Expected output to include "${expected}"`,
+        expected,
+        actual: output,
+      }
+    }
+
+    return { passed: true }
+  }
+}

test/snippets/directives/expectOutputRegex.ts

@@ -0,0 +1,25 @@
+/**
+ * expect-output-regex directive
+ */
+
+import type { AssertionDirective } from "./types.js"
+
+export const expectOutputRegex: AssertionDirective = {
+  type: "assertion",
+  name: "expect-output-regex",
+  handler: (executionResult, directive) => {
+    const output = executionResult.logs.join("\n")
+    const pattern = directive.args as RegExp
+
+    if (!pattern.test(output)) {
+      return {
+        passed: false,
+        message: `Expected output to match ${pattern}`,
+        expected: pattern,
+        actual: output,
+      }
+    }
+
+    return { passed: true }
+  }
+}

test/snippets/directives/expectReturn.ts

@@ -0,0 +1,36 @@
+/**
+ * expect-return directive
+ */
+
+import type { AssertionDirective } from "./types.js"
+
+export const expectReturn: AssertionDirective = {
+  type: "assertion",
+  name: "expect-return",
+  handler: (executionResult, directive) => {
+    const expected = String(directive.args)
+
+    // Handle undefined/null return values explicitly
+    if (executionResult.returnValue === undefined || executionResult.returnValue === null) {
+      return {
+        passed: false,
+        message: `Expected return value to include "${expected}", but got ${executionResult.returnValue}`,
+        expected,
+        actual: executionResult.returnValue,
+      }
+    }
+
+    const returnValueStr = JSON.stringify(executionResult.returnValue)
+
+    if (!returnValueStr.includes(expected)) {
+      return {
+        passed: false,
+        message: `Expected return value to include "${expected}"`,
+        expected,
+        actual: returnValueStr,
+      }
+    }
+
+    return { passed: true }
+  }
+}

test/snippets/directives/expectReturnJson.ts

@@ -0,0 +1,15 @@
+/**
+ * expect-return-json directive
+ */
+
+import type { AssertionDirective } from "./types.js"
+import { parseAssertionSpec, executeAssertion } from "../assertions.js"
+
+export const expectReturnJson: AssertionDirective = {
+  type: "assertion",
+  name: "expect-return-json",
+  handler: (executionResult, directive) => {
+    const spec = parseAssertionSpec(directive.args as string | Record<string, unknown>)
+    return executeAssertion(spec.type, executionResult.returnValue, spec.args)
+  }
+}

test/snippets/directives/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Directive registry - exports all directive handlers
+ */
+
+export * from "./types.js"
+export { skip } from "./skip.js"
+export { description } from "./description.js"
+export { expectError } from "./expectError.js"
+export { expectNoError } from "./expectNoError.js"
+export { expectOutput } from "./expectOutput.js"
+export { expectOutputRegex } from "./expectOutputRegex.js"
+export { expectReturn } from "./expectReturn.js"
+export { expectReturnJson } from "./expectReturnJson.js"
+export { awaitDirective } from "./await.js"
+export { timeoutDirective } from "./timeout.js"
+export { returnStatementDirective } from "./returnStatement.js"
+
+import type { AnyDirective } from "./types.js"
+import { skip } from "./skip.js"
+import { description } from "./description.js"
+import { expectError } from "./expectError.js"
+import { expectNoError } from "./expectNoError.js"
+import { expectOutput } from "./expectOutput.js"
+import { expectOutputRegex } from "./expectOutputRegex.js"
+import { expectReturn } from "./expectReturn.js"
+import { expectReturnJson } from "./expectReturnJson.js"
+import { awaitDirective } from "./await.js"
+import { timeoutDirective } from "./timeout.js"
+import { returnStatementDirective } from "./returnStatement.js"
+
+/**
+ * All built-in directives
+ */
+export const allDirectives: AnyDirective[] = [
+  skip,
+  description,
+  expectError,
+  expectNoError,
+  expectOutput,
+  expectOutputRegex,
+  expectReturn,
+  expectReturnJson,
+  awaitDirective,
+  timeoutDirective,
+  returnStatementDirective,
+]
+
+/**
+ * Directives grouped by type
+ */
+export const directives = {
+  control: [skip, description],
+  assertion: [expectError, expectNoError, expectOutput, expectOutputRegex, expectReturn, expectReturnJson],
+  transform: [awaitDirective, returnStatementDirective],
+  config: [timeoutDirective],
+}
+
+/**
+ * Get directive by name
+ */
+export function getDirectiveByName(name: string): AnyDirective | undefined {
+  return allDirectives.find(d => d.name === name)
+}

test/snippets/directives/returnStatement.ts

@@ -0,0 +1,19 @@
+/**
+ * return-statement directive - adds return statement for variable
+ */
+
+import type { TransformDirective } from "./types.js"
+
+export const returnStatementDirective: TransformDirective = {
+  type: "transform",
+  name: "return-statement",
+  description: "Specify a custom variable to return when the snippet ends with a variable assignment",
+  handler: (snippet, _directive) => {
+    // Mark that this snippet needs return statement injection
+    // The actual transformation happens in the transformer module
+    return {
+      code: snippet.code,
+      modified: false // Transformation will be done by transformer
+    }
+  }
+}