@sharpee/transcript-tester 0.9.61-beta

package/src/story-loader.ts

@@ -0,0 +1,168 @@
+/**
+ * Story Loader
+ *
+ * Dynamically loads and initializes a story for testing.
+ */
+
+import * as path from 'path';
+import { GameEngine, TurnResult, SequencedEvent } from '@sharpee/engine';
+import { WorldModel, EntityType } from '@sharpee/world-model';
+import { Parser } from '@sharpee/parser-en-us';
+import { PerceptionService } from '@sharpee/stdlib';
+// @ts-ignore
+import { LanguageProvider } from '@sharpee/lang-en-us';
+
+/**
+ * Interface for a story module
+ */
+interface StoryModule {
+  story?: any;
+  default?: any;
+}
+
+/**
+ * A testable game instance
+ */
+export interface TestableGame {
+  engine: GameEngine;
+  world: WorldModel;
+  lastOutput: string;
+  lastEvents: SequencedEvent[];
+  lastTurnResult: TurnResult | null;
+  executeCommand(input: string): Promise<string>;
+}
+
+/**
+ * Load a story from a path and create a testable game instance
+ */
+export async function loadStory(storyPath: string): Promise<TestableGame> {
+  // Resolve the story path
+  const resolvedPath = path.isAbsolute(storyPath)
+    ? storyPath
+    : path.resolve(process.cwd(), storyPath);
+
+  // Try to load the story module
+  let storyModule: StoryModule;
+  try {
+    // Try loading the compiled dist version first
+    const distPath = path.join(resolvedPath, 'dist', 'index.js');
+    storyModule = require(distPath);
+  } catch (e) {
+    try {
+      // Fall back to src (for ts-node environments)
+      const srcPath = path.join(resolvedPath, 'src', 'index.ts');
+      storyModule = require(srcPath);
+    } catch (e2) {
+      throw new Error(`Could not load story from ${storyPath}: ${e}`);
+    }
+  }
+
+  const story = storyModule.story || storyModule.default;
+  if (!story) {
+    throw new Error(`Story module at ${storyPath} does not export 'story' or 'default'`);
+  }
+
+  // Create the game instance
+  return createTestableGame(story);
+}
+
+/**
+ * Create a testable game from a story instance
+ */
+export function createTestableGame(story: any): TestableGame {
+  // Create world and player
+  const world = new WorldModel();
+  const player = world.createEntity('player', EntityType.ACTOR);
+  world.setPlayer(player.id);
+
+  // Create parser and language
+  const language = new LanguageProvider();
+  const parser = new Parser(language);
+
+  // Extend parser and language with story-specific vocabulary
+  if (story.extendParser) {
+    story.extendParser(parser);
+  }
+  if (story.extendLanguage) {
+    story.extendLanguage(language);
+  }
+
+  // Create perception service
+  const perceptionService = new PerceptionService();
+
+  // Create engine (TextService created internally from language provider)
+  const engine = new GameEngine({
+    world,
+    player,
+    parser,
+    language,
+    perceptionService,
+  });
+
+  // Set the story and start
+  engine.setStory(story);
+  engine.start();
+
+  // Capture text output and events
+  let lastOutput = '';
+  let outputBuffer: string[] = [];
+  let lastEvents: SequencedEvent[] = [];
+  let lastTurnResult: TurnResult | null = null;
+
+  engine.on('text:output', (text: string) => {
+    outputBuffer.push(text);
+  });
+
+  // Capture ALL events through the event emitter (includes scheduler/NPC events)
+  let eventBuffer: SequencedEvent[] = [];
+  engine.on('event', (event: SequencedEvent) => {
+    eventBuffer.push(event);
+  });
+
+  // Create the testable game interface
+  const testableGame: TestableGame = {
+    engine,
+    world,
+    lastOutput: '',
+    lastEvents: [],
+    lastTurnResult: null,
+
+    async executeCommand(input: string): Promise<string> {
+      outputBuffer = [];
+      eventBuffer = []; // Reset event buffer for this command
+      lastEvents = [];
+      lastTurnResult = null;
+
+      try {
+        const result = await engine.executeTurn(input);
+        if (result) {
+          lastTurnResult = result;
+          // Use eventBuffer which captures ALL events (action + NPC + scheduler)
+          lastEvents = eventBuffer;
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        outputBuffer.push(`Error: ${errorMessage}`);
+      }
+
+      lastOutput = outputBuffer.join('\n');
+      testableGame.lastOutput = lastOutput;
+      testableGame.lastEvents = lastEvents;
+      testableGame.lastTurnResult = lastTurnResult;
+      return lastOutput;
+    },
+  };
+
+  return testableGame;
+}
+
+/**
+ * Find all transcript files in a directory
+ */
+export function findTranscripts(dir: string, pattern: string = '*.transcript'): string[] {
+  const glob = require('glob');
+  const resolvedDir = path.isAbsolute(dir) ? dir : path.resolve(process.cwd(), dir);
+
+  const files = glob.sync(path.join(resolvedDir, '**', pattern));
+  return files;
+}

package/src/types.ts

@@ -0,0 +1,244 @@
+/**
+ * Transcript Testing Types
+ *
+ * Defines the structure of parsed transcripts and test results.
+ */
+
+// ============================================================================
+// Directive Types (ADR-092: Smart Transcript Directives)
+// ============================================================================
+
+/**
+ * Types of control flow directives
+ */
+export type DirectiveType =
+  | 'goal'        // [GOAL: name]
+  | 'end_goal'    // [END GOAL]
+  | 'requires'    // [REQUIRES: condition]
+  | 'ensures'     // [ENSURES: condition]
+  | 'if'          // [IF: condition]
+  | 'end_if'      // [END IF]
+  | 'while'       // [WHILE: condition]
+  | 'end_while'   // [END WHILE]
+  | 'navigate'    // [NAVIGATE TO: "Room Name"]
+  | 'save'        // $save <name>
+  | 'restore'     // $restore <name>
+  | 'test-command'; // $teleport, $take, $kill, etc. (ext-testing)
+
+/**
+ * A control flow directive in the transcript
+ */
+export interface Directive {
+  type: DirectiveType;
+  lineNumber: number;
+  condition?: string;   // For IF/WHILE/REQUIRES/ENSURES: the condition expression
+  target?: string;      // For NAVIGATE: the target room name
+  goalName?: string;    // For GOAL: the goal name
+  saveName?: string;    // For SAVE/RESTORE: the checkpoint name
+  testCommand?: string; // For test-command: the full $command input (e.g., "$teleport kitchen")
+}
+
+/**
+ * A goal segment with its preconditions, postconditions, and content
+ */
+export interface GoalDefinition {
+  name: string;
+  lineNumber: number;
+  requires: string[];   // Precondition expressions
+  ensures: string[];    // Postcondition expressions
+  startIndex: number;   // Index in items array where goal content starts
+  endIndex: number;     // Index in items array where goal ends
+}
+
+/**
+ * Result of executing a goal
+ */
+export interface GoalResult {
+  name: string;
+  success: boolean;
+  requiresResults: ConditionResult[];
+  ensuresResults: ConditionResult[];
+  commandsExecuted: number;
+  error?: string;
+}
+
+/**
+ * Result of evaluating a condition
+ */
+export interface ConditionResult {
+  met: boolean;
+  reason: string;  // Human-readable explanation
+}
+
+/**
+ * Result of executing a NAVIGATE directive
+ */
+export interface NavigateResult {
+  success: boolean;
+  path: string[];       // Room names traversed
+  commands: string[];   // GO commands executed
+  error?: string;
+}
+
+/**
+ * A comment annotation from the transcript (# lines)
+ */
+export interface TranscriptComment {
+  lineNumber: number;
+  text: string;
+}
+
+/**
+ * A transcript item - either a command, directive, or comment
+ */
+export interface TranscriptItem {
+  type: 'command' | 'directive' | 'comment';
+  command?: TranscriptCommand;
+  directive?: Directive;
+  comment?: TranscriptComment;
+}
+
+// ============================================================================
+// Original Types
+// ============================================================================
+
+/**
+ * Header metadata from a transcript file
+ */
+export interface TranscriptHeader {
+  title?: string;
+  story?: string;
+  author?: string;
+  description?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * A single assertion about command output, events, or state
+ */
+export interface Assertion {
+  type: 'ok' | 'ok-contains' | 'ok-matches' | 'ok-not-contains' | 'fail' | 'skip' | 'todo'
+      | 'event-count' | 'event-assert' | 'state-assert';
+  value?: string;      // For contains/matches
+  pattern?: RegExp;    // For regex matches
+  reason?: string;     // For fail/todo
+
+  // Event assertions
+  eventCount?: number;          // For event-count assertion
+  assertTrue?: boolean;         // For event-assert and state-assert: true = must exist, false = must not exist
+  eventPosition?: number;       // For event-assert: optional 1-based position (omit for "any position")
+  eventType?: string;           // For event-assert: the event type to match
+  eventData?: Record<string, any>; // For event-assert: data properties to match
+
+  // State assertions
+  stateExpression?: string;     // For state-assert: the expression to evaluate (e.g., "egg.location = thief")
+}
+
+/**
+ * A single command with its expected output and assertions
+ */
+export interface TranscriptCommand {
+  lineNumber: number;
+  input: string;
+  expectedOutput: string[];
+  assertions: Assertion[];
+}
+
+/**
+ * A fully parsed transcript file
+ */
+export interface Transcript {
+  filePath: string;
+  header: TranscriptHeader;
+  commands: TranscriptCommand[];         // Legacy: just commands (for backwards compat)
+  items?: TranscriptItem[];              // New: commands + directives in order
+  goals?: GoalDefinition[];              // Parsed goal segments
+  comments: string[];
+}
+
+/**
+ * Simplified event info for test results
+ */
+export interface TestEventInfo {
+  type: string;
+  data: Record<string, any>;
+}
+
+/**
+ * Result of running a single command
+ */
+export interface CommandResult {
+  command: TranscriptCommand;
+  actualOutput: string;
+  actualEvents: TestEventInfo[];
+  passed: boolean;
+  expectedFailure: boolean;  // Was marked [FAIL]
+  skipped: boolean;          // Was marked [SKIP] or [TODO]
+  assertionResults: AssertionResult[];
+  error?: string;
+}
+
+/**
+ * Result of a single assertion check
+ */
+export interface AssertionResult {
+  assertion: Assertion;
+  passed: boolean;
+  message?: string;
+}
+
+/**
+ * Result of running an entire transcript
+ */
+export interface TranscriptResult {
+  transcript: Transcript;
+  commands: CommandResult[];
+  passed: number;
+  failed: number;
+  expectedFailures: number;
+  skipped: number;
+  duration: number;  // milliseconds
+}
+
+/**
+ * Result of running multiple transcripts
+ */
+export interface TestRunResult {
+  transcripts: TranscriptResult[];
+  totalPassed: number;
+  totalFailed: number;
+  totalExpectedFailures: number;
+  totalSkipped: number;
+  totalDuration: number;
+}
+
+/**
+ * Options for the test runner
+ */
+/**
+ * Interface for ext-testing extension (optional)
+ */
+export interface TestingExtensionInterface {
+  executeTestCommand(input: string, world: any): { success: boolean; output: string[]; error?: string };
+  /** Set context for annotation commands (called after each command execution) */
+  setCommandContext?(command: string, response: string): void;
+  /** Add an annotation directly (for # comments) */
+  addAnnotation?(type: string, text: string, world: any): any;
+}
+
+export interface RunnerOptions {
+  verbose?: boolean;
+  stopOnFailure?: boolean;
+  updateExpected?: boolean;
+  filter?: string;  // Only run commands matching this pattern
+  savesDirectory?: string;  // Directory for $save/$restore checkpoints
+  testingExtension?: TestingExtensionInterface;  // Optional ext-testing integration
+}
+
+/**
+ * Story loader function type
+ */
+export type StoryLoader = (storyPath: string) => Promise<{
+  engine: any;  // GameEngine
+  story: any;   // Story instance
+}>;

package/tsconfig.esm.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base-esm.json",
+  "compilerOptions": {
+    "outDir": "./dist-esm",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "dist-esm", "**/*.test.ts", "**/*.spec.ts"]
+}