@canonical/summon 0.1.0

package/src/dry-run.ts

@@ -0,0 +1,434 @@
+/**
+ * Dry-Run Interpreter
+ *
+ * This module provides interpreters for testing and previewing tasks
+ * without actually executing their effects.
+ */
+
+import { TaskExecutionError } from "./interpreter.js";
+import type { DryRunResult, Effect, Task } from "./types.js";
+
+// =============================================================================
+// Mock Effect Results
+// =============================================================================
+
+/**
+ * Generate a mock result for an effect.
+ * This allows tasks to continue executing in dry-run mode.
+ */
+export const mockEffect = (effect: Effect): unknown => {
+  switch (effect._tag) {
+    case "ReadFile":
+      return `[mock content of ${effect.path}]`;
+
+    case "WriteFile":
+    case "AppendFile":
+    case "CopyFile":
+    case "CopyDirectory":
+    case "DeleteFile":
+    case "DeleteDirectory":
+    case "MakeDir":
+    case "Log":
+    case "WriteContext":
+      return undefined;
+
+    case "Exists":
+      return true;
+
+    case "Glob":
+      return [];
+
+    case "Exec":
+      return { stdout: "", stderr: "", exitCode: 0 };
+
+    case "Prompt":
+      // Return default or first choice
+      switch (effect.question.type) {
+        case "text":
+          return effect.question.default ?? "";
+        case "confirm":
+          return effect.question.default ?? false;
+        case "select":
+          return (
+            effect.question.default ?? effect.question.choices[0]?.value ?? ""
+          );
+        case "multiselect":
+          return effect.question.default ?? [];
+      }
+      break;
+
+    case "ReadContext":
+      return undefined;
+
+    case "Parallel":
+      return effect.tasks.map((t) => {
+        const result = dryRun(t);
+        return result.value;
+      });
+
+    case "Race":
+      if (effect.tasks.length > 0) {
+        return dryRun(effect.tasks[0]).value;
+      }
+      return undefined;
+  }
+};
+
+// =============================================================================
+// Dry-Run Interpreter
+// =============================================================================
+
+/**
+ * Run a task in dry-run mode, collecting effects without executing them.
+ * Tracks virtual filesystem state to properly handle exists() checks.
+ */
+export const dryRun = <A>(task: Task<A>): DryRunResult<A> => {
+  const effects: Effect[] = [];
+  // Track files/dirs that would be created during dry-run
+  const virtualFs = new Set<string>();
+
+  const mockEffectWithFs = (effect: Effect): unknown => {
+    switch (effect._tag) {
+      case "WriteFile":
+      case "AppendFile":
+        virtualFs.add(effect.path);
+        return undefined;
+      case "MakeDir":
+        virtualFs.add(effect.path);
+        return undefined;
+      case "Exists":
+        // Check if file was "created" during this dry-run
+        return virtualFs.has(effect.path);
+      default:
+        return mockEffect(effect);
+    }
+  };
+
+  const run = <T>(t: Task<T>): T => {
+    switch (t._tag) {
+      case "Pure":
+        return t.value;
+
+      case "Fail":
+        throw new TaskExecutionError(t.error);
+
+      case "Effect": {
+        const effect = t.effect;
+
+        // Handle Parallel specially - collect effects from all child tasks
+        if (effect._tag === "Parallel") {
+          const results = effect.tasks.map((childTask) => {
+            const childResult = dryRunWithVirtualFs(childTask, virtualFs);
+            effects.push(...childResult.effects);
+            return childResult.value;
+          });
+          return run(t.cont(results) as Task<T>);
+        }
+
+        // Handle Race specially - collect effects from first child task
+        if (effect._tag === "Race") {
+          if (effect.tasks.length > 0) {
+            const childResult = dryRunWithVirtualFs(effect.tasks[0], virtualFs);
+            effects.push(...childResult.effects);
+            return run(t.cont(childResult.value) as Task<T>);
+          }
+          return run(t.cont(undefined) as Task<T>);
+        }
+
+        // Regular effects - add to list and mock
+        effects.push(effect);
+        const mockResult = mockEffectWithFs(effect);
+        return run(t.cont(mockResult) as Task<T>);
+      }
+    }
+  };
+
+  const value = run(task);
+  return { value, effects };
+};
+
+/**
+ * Internal helper: Run dry-run with shared virtual filesystem state.
+ */
+const dryRunWithVirtualFs = <A>(
+  task: Task<A>,
+  virtualFs: Set<string>,
+): DryRunResult<A> => {
+  const effects: Effect[] = [];
+
+  const mockEffectWithFs = (effect: Effect): unknown => {
+    switch (effect._tag) {
+      case "WriteFile":
+      case "AppendFile":
+        virtualFs.add(effect.path);
+        return undefined;
+      case "MakeDir":
+        virtualFs.add(effect.path);
+        return undefined;
+      case "Exists":
+        return virtualFs.has(effect.path);
+      default:
+        return mockEffect(effect);
+    }
+  };
+
+  const run = <T>(t: Task<T>): T => {
+    switch (t._tag) {
+      case "Pure":
+        return t.value;
+
+      case "Fail":
+        throw new TaskExecutionError(t.error);
+
+      case "Effect": {
+        const effect = t.effect;
+
+        if (effect._tag === "Parallel") {
+          const results = effect.tasks.map((childTask) => {
+            const childResult = dryRunWithVirtualFs(childTask, virtualFs);
+            effects.push(...childResult.effects);
+            return childResult.value;
+          });
+          return run(t.cont(results) as Task<T>);
+        }
+
+        if (effect._tag === "Race") {
+          if (effect.tasks.length > 0) {
+            const childResult = dryRunWithVirtualFs(effect.tasks[0], virtualFs);
+            effects.push(...childResult.effects);
+            return run(t.cont(childResult.value) as Task<T>);
+          }
+          return run(t.cont(undefined) as Task<T>);
+        }
+
+        effects.push(effect);
+        const mockResult = mockEffectWithFs(effect);
+        return run(t.cont(mockResult) as Task<T>);
+      }
+    }
+  };
+
+  const value = run(task);
+  return { value, effects };
+};
+
+/**
+ * Run a task in dry-run mode with custom mock values.
+ */
+export const dryRunWith = <A>(
+  task: Task<A>,
+  mocks: Map<string, (effect: Effect) => unknown>,
+): DryRunResult<A> => {
+  const effects: Effect[] = [];
+
+  const getMock = (effect: Effect): unknown => {
+    const customMock = mocks.get(effect._tag);
+    if (customMock) {
+      return customMock(effect);
+    }
+    return mockEffect(effect);
+  };
+
+  const run = (t: Task<A>): A => {
+    switch (t._tag) {
+      case "Pure":
+        return t.value;
+
+      case "Fail":
+        throw new TaskExecutionError(t.error);
+
+      case "Effect": {
+        effects.push(t.effect);
+        const mockResult = getMock(t.effect);
+        return run(t.cont(mockResult));
+      }
+    }
+  };
+
+  const value = run(task);
+  return { value, effects };
+};
+
+// =============================================================================
+// Effect Collection
+// =============================================================================
+
+/**
+ * Collect all effects from a task without running to completion.
+ * Useful for testing what effects a task would produce.
+ */
+export const collectEffects = <A>(task: Task<A>): Effect[] => {
+  const effects: Effect[] = [];
+
+  const collect = (t: Task<unknown>): void => {
+    switch (t._tag) {
+      case "Pure":
+      case "Fail":
+        return;
+
+      case "Effect":
+        effects.push(t.effect);
+        collect(t.cont(mockEffect(t.effect)));
+    }
+  };
+
+  collect(task);
+  return effects;
+};
+
+/**
+ * Count the number of effects of each type.
+ */
+export const countEffects = (effects: Effect[]): Record<string, number> => {
+  const counts: Record<string, number> = {};
+  for (const effect of effects) {
+    counts[effect._tag] = (counts[effect._tag] ?? 0) + 1;
+  }
+  return counts;
+};
+
+/**
+ * Filter effects by type.
+ */
+export const filterEffects = <T extends Effect["_tag"]>(
+  effects: Effect[],
+  tag: T,
+): Array<Extract<Effect, { _tag: T }>> =>
+  effects.filter((e): e is Extract<Effect, { _tag: T }> => e._tag === tag);
+
+/**
+ * Get all file write operations from effects.
+ */
+export const getFileWrites = (
+  effects: Effect[],
+): Array<{ path: string; content: string }> =>
+  filterEffects(effects, "WriteFile").map((e) => ({
+    path: e.path,
+    content: e.content,
+  }));
+
+/**
+ * Get all file paths that would be created/modified.
+ */
+export const getAffectedFiles = (effects: Effect[]): string[] => {
+  const files = new Set<string>();
+
+  for (const effect of effects) {
+    switch (effect._tag) {
+      case "WriteFile":
+      case "AppendFile":
+      case "DeleteFile":
+        files.add(effect.path);
+        break;
+      case "CopyFile":
+        files.add(effect.dest);
+        break;
+      case "MakeDir":
+        files.add(effect.path);
+        break;
+    }
+  }
+
+  return Array.from(files).sort();
+};
+
+// =============================================================================
+// Test Utilities
+// =============================================================================
+
+/**
+ * Assert that a task produces specific effects.
+ */
+export const assertEffects = <A>(
+  task: Task<A>,
+  expectedEffects: Partial<Effect>[],
+): void => {
+  const { effects } = dryRun(task);
+
+  if (effects.length !== expectedEffects.length) {
+    throw new Error(
+      `Expected ${expectedEffects.length} effects, got ${effects.length}`,
+    );
+  }
+
+  for (let i = 0; i < effects.length; i++) {
+    const actual = effects[i];
+    const expected = expectedEffects[i];
+
+    for (const [key, value] of Object.entries(expected)) {
+      if ((actual as Record<string, unknown>)[key] !== value) {
+        throw new Error(
+          `Effect ${i}: expected ${key} to be ${JSON.stringify(value)}, got ${JSON.stringify((actual as Record<string, unknown>)[key])}`,
+        );
+      }
+    }
+  }
+};
+
+/**
+ * Assert that a task would write specific files.
+ */
+export const assertFileWrites = <A>(
+  task: Task<A>,
+  expectedFiles: string[],
+): void => {
+  const { effects } = dryRun(task);
+  const actualFiles = getAffectedFiles(effects);
+  const expected = expectedFiles.sort();
+
+  if (actualFiles.length !== expected.length) {
+    throw new Error(
+      `Expected ${expected.length} file writes, got ${actualFiles.length}\n` +
+        `Expected: ${expected.join(", ")}\n` +
+        `Actual: ${actualFiles.join(", ")}`,
+    );
+  }
+
+  for (let i = 0; i < expected.length; i++) {
+    if (actualFiles[i] !== expected[i]) {
+      throw new Error(`Expected file ${expected[i]}, got ${actualFiles[i]}`);
+    }
+  }
+};
+
+/**
+ * Create a task result matcher for testing.
+ */
+export const expectTask = <A>(task: Task<A>) => {
+  const result = dryRun(task);
+
+  return {
+    toHaveValue: (expected: A) => {
+      if (result.value !== expected) {
+        throw new Error(
+          `Expected value ${JSON.stringify(expected)}, got ${JSON.stringify(result.value)}`,
+        );
+      }
+    },
+
+    toHaveEffectCount: (count: number) => {
+      if (result.effects.length !== count) {
+        throw new Error(
+          `Expected ${count} effects, got ${result.effects.length}`,
+        );
+      }
+    },
+
+    toWriteFile: (path: string) => {
+      const writes = filterEffects(result.effects, "WriteFile");
+      if (!writes.some((w) => w.path === path)) {
+        throw new Error(`Expected task to write file ${path}`);
+      }
+    },
+
+    toNotWriteFile: (path: string) => {
+      const writes = filterEffects(result.effects, "WriteFile");
+      if (writes.some((w) => w.path === path)) {
+        throw new Error(`Expected task to not write file ${path}`);
+      }
+    },
+
+    effects: result.effects,
+    value: result.value,
+  };
+};

package/src/effect.ts

@@ -0,0 +1,224 @@
+/**
+ * Effect Constructors
+ *
+ * This module provides constructor functions for creating Effect values.
+ * Effects are pure data that describe operations without performing them.
+ */
+
+import type { Effect, LogLevel, PromptQuestion, Task } from "./types.js";
+
+// =============================================================================
+// File System Effect Constructors
+// =============================================================================
+
+export const readFileEffect = (path: string): Effect => ({
+  _tag: "ReadFile",
+  path,
+});
+
+export const writeFileEffect = (path: string, content: string): Effect => ({
+  _tag: "WriteFile",
+  path,
+  content,
+});
+
+export const appendFileEffect = (
+  path: string,
+  content: string,
+  createIfMissing = true,
+): Effect => ({
+  _tag: "AppendFile",
+  path,
+  content,
+  createIfMissing,
+});
+
+export const copyFileEffect = (source: string, dest: string): Effect => ({
+  _tag: "CopyFile",
+  source,
+  dest,
+});
+
+export const copyDirectoryEffect = (source: string, dest: string): Effect => ({
+  _tag: "CopyDirectory",
+  source,
+  dest,
+});
+
+export const deleteFileEffect = (path: string): Effect => ({
+  _tag: "DeleteFile",
+  path,
+});
+
+export const deleteDirectoryEffect = (path: string): Effect => ({
+  _tag: "DeleteDirectory",
+  path,
+});
+
+export const makeDirEffect = (path: string, recursive = true): Effect => ({
+  _tag: "MakeDir",
+  path,
+  recursive,
+});
+
+export const existsEffect = (path: string): Effect => ({
+  _tag: "Exists",
+  path,
+});
+
+export const globEffect = (pattern: string, cwd: string): Effect => ({
+  _tag: "Glob",
+  pattern,
+  cwd,
+});
+
+// =============================================================================
+// Process Effect Constructors
+// =============================================================================
+
+export const execEffect = (
+  command: string,
+  args: string[],
+  cwd?: string,
+): Effect => ({
+  _tag: "Exec",
+  command,
+  args,
+  cwd,
+});
+
+// =============================================================================
+// Prompt Effect Constructors
+// =============================================================================
+
+export const promptEffect = (question: PromptQuestion): Effect => ({
+  _tag: "Prompt",
+  question,
+});
+
+// =============================================================================
+// Logging Effect Constructors
+// =============================================================================
+
+export const logEffect = (level: LogLevel, message: string): Effect => ({
+  _tag: "Log",
+  level,
+  message,
+});
+
+// =============================================================================
+// Context Effect Constructors
+// =============================================================================
+
+export const readContextEffect = (key: string): Effect => ({
+  _tag: "ReadContext",
+  key,
+});
+
+export const writeContextEffect = (key: string, value: unknown): Effect => ({
+  _tag: "WriteContext",
+  key,
+  value,
+});
+
+// =============================================================================
+// Concurrency Effect Constructors
+// =============================================================================
+
+export const parallelEffect = (tasks: Task<unknown>[]): Effect => ({
+  _tag: "Parallel",
+  tasks,
+});
+
+export const raceEffect = (tasks: Task<unknown>[]): Effect => ({
+  _tag: "Race",
+  tasks,
+});
+
+// =============================================================================
+// Effect Utilities
+// =============================================================================
+
+/**
+ * Get a human-readable description of an effect.
+ */
+export const describeEffect = (effect: Effect): string => {
+  switch (effect._tag) {
+    case "ReadFile":
+      return `Read file: ${effect.path}`;
+    case "WriteFile":
+      return `Write file: ${effect.path} (${effect.content.length} bytes)`;
+    case "AppendFile":
+      return `Append to file: ${effect.path} (${effect.content.length} bytes)${effect.createIfMissing ? " [create if missing]" : ""}`;
+    case "CopyFile":
+      return `Copy file: ${effect.source} → ${effect.dest}`;
+    case "CopyDirectory":
+      return `Copy directory: ${effect.source} → ${effect.dest}`;
+    case "DeleteFile":
+      return `Delete file: ${effect.path}`;
+    case "DeleteDirectory":
+      return `Delete directory: ${effect.path}`;
+    case "MakeDir":
+      return `Created ${effect.path}/`;
+    case "Exists":
+      return `Check exists: ${effect.path}`;
+    case "Glob":
+      return `Glob: ${effect.pattern} in ${effect.cwd}`;
+    case "Exec":
+      return `Execute: ${effect.command} ${effect.args.join(" ")}`;
+    case "Prompt":
+      return `Prompt: ${effect.question.message}`;
+    case "Log":
+      return `Log [${effect.level}]: ${effect.message}`;
+    case "ReadContext":
+      return `Read context: ${effect.key}`;
+    case "WriteContext":
+      return `Write context: ${effect.key}`;
+    case "Parallel":
+      return `Parallel: ${effect.tasks.length} tasks`;
+    case "Race":
+      return `Race: ${effect.tasks.length} tasks`;
+  }
+};
+
+/**
+ * Check if an effect modifies the file system.
+ */
+export const isWriteEffect = (effect: Effect): boolean => {
+  switch (effect._tag) {
+    case "WriteFile":
+    case "AppendFile":
+    case "CopyFile":
+    case "CopyDirectory":
+    case "DeleteFile":
+    case "DeleteDirectory":
+    case "MakeDir":
+      return true;
+    default:
+      return false;
+  }
+};
+
+/**
+ * Get the file paths affected by an effect.
+ */
+export const getAffectedPaths = (effect: Effect): string[] => {
+  switch (effect._tag) {
+    case "ReadFile":
+    case "WriteFile":
+    case "AppendFile":
+    case "DeleteFile":
+    case "MakeDir":
+    case "Exists":
+      return [effect.path];
+    case "CopyFile":
+    case "CopyDirectory":
+      return [effect.source, effect.dest];
+    case "DeleteDirectory":
+      return [effect.path];
+    case "Glob":
+      return [effect.cwd];
+    default:
+      return [];
+  }
+};