// Good: Clear, typed, well-documented
/**
 * Creates a new QNCE engine instance with the provided story data.
 * 
 * @param story - The story data to load
 * @param options - Configuration options for the engine
 * @returns A new QNCEEngine instance
 * @throws {ValidationError} When story data is invalid
 */
export function createQNCEEngine(
  story: QNCEStory,
  options: QNCEEngineOptions = {}
): QNCEEngine {
  // Implementation here
}

// Bad: Unclear, untyped, undocumented
export function create(story: any, opts?: any): any {
  // Implementation here
}

// Example test structure
describe('QNCEEngine', () => {
  describe('Core Functionality', () => {
    it('should create engine with valid story', () => {
      const engine = createQNCEEngine(DEMO_STORY);
      expect(engine.getCurrentNode()).toBeDefined();
      expect(engine.getCurrentNode().id).toBe('start');
    });

    it('should handle invalid choice gracefully', () => {
      const engine = createQNCEEngine(DEMO_STORY);
      expect(() => engine.makeChoice(999)).toThrow('Invalid choice index');
    });
  });

  describe('Performance', () => {
    it('should complete state transitions within target time', () => {
      const engine = createQNCEEngine(LARGE_STORY);
      const startTime = performance.now();
      
      engine.makeChoice(0);
      
      const endTime = performance.now();
      expect(endTime - startTime).toBeLessThan(5); // 5ms target
    });
  });
});

/**
 * Makes a choice and advances the story to the next node.
 * 
 * @param choiceIndex - Zero-based index of the choice to make
 * @throws {Error} When choice index is out of bounds
 * @throws {ValidationError} When choice conditions are not met
 * 
 * @example
 * ```typescript
 * const choices = engine.getAvailableChoices();
 * if (choices.length > 0) {
 *   engine.makeChoice(0); // Make the first choice
 * }
 * ```
 */
makeChoice(choiceIndex: number): void {
  // Implementation
}

// tests/unit/engine/core.test.ts
import { createQNCEEngine } from '../../../src/engine/core';
import { DEMO_STORY } from '../../../src/engine/demo-story';

describe('createQNCEEngine', () => {
  it('should create engine with default options', () => {
    const engine = createQNCEEngine(DEMO_STORY);
    
    expect(engine).toBeDefined();
    expect(engine.getCurrentNode().id).toBe('start');
    expect(engine.getFlags()).toEqual({});
  });

  it('should apply custom options', () => {
    const engine = createQNCEEngine(DEMO_STORY, {
      enablePerformanceMode: true,
      enableBranching: true
    });
    
    expect(engine.isPerformanceModeEnabled()).toBe(true);
    expect(engine.isBranchingEnabled()).toBe(true);
  });
});

// tests/integration/frameworks/react.test.tsx
import React from 'react';
import { render, fireEvent, screen } from '@testing-library/react';
import { StoryComponent } from '../../../examples/react/StoryComponent';
import { DEMO_STORY } from '../../../src/engine/demo-story';

describe('React Integration', () => {
  it('should render story and handle choices', () => {
    render(<StoryComponent story={DEMO_STORY} />);
    
    // Check initial state
    expect(screen.getByText(/welcome to the demo/i)).toBeInTheDocument();
    
    // Make a choice
    const firstChoice = screen.getByText(/explore the forest/i);
    fireEvent.click(firstChoice);
    
    // Verify navigation
    expect(screen.getByText(/you enter the dark forest/i)).toBeInTheDocument();
  });
});

// tests/performance/state-transitions.test.ts
import { createQNCEEngine } from '../../src/engine/core';
import { generateLargeStory } from '../fixtures/large-story';

describe('State Transition Performance', () => {
  it('should complete transitions within target time', () => {
    const largeStory = generateLargeStory(1000); // 1000 nodes
    const engine = createQNCEEngine(largeStory, {
      enablePerformanceMode: true
    });

    const measurements: number[] = [];
    
    // Measure 100 transitions
    for (let i = 0; i < 100; i++) {
      const startTime = performance.now();
      
      if (engine.getAvailableChoices().length > 0) {
        engine.makeChoice(0);
      }
      
      const endTime = performance.now();
      measurements.push(endTime - startTime);
    }

    const avgTime = measurements.reduce((a, b) => a + b) / measurements.length;
    const maxTime = Math.max(...measurements);

    expect(avgTime).toBeLessThan(5); // 5ms average target
    expect(maxTime).toBeLessThan(20); // 20ms maximum target
  });
});

// Include performance assertions in relevant tests
it('should maintain performance targets', () => {
  const engine = createQNCEEngine(story, { enablePerformanceMode: true });
  
  // Warm up
  for (let i = 0; i < 10; i++) {
    engine.makeChoice(0);
    engine.reset();
  }
  
  // Measure
  const startTime = performance.now();
  engine.makeChoice(0);
  const endTime = performance.now();
  
  expect(endTime - startTime).toBeLessThan(5);
});

// Check for memory leaks in long-running tests
it('should not leak memory during extended use', () => {
  const engine = createQNCEEngine(story);
  const initialMemory = process.memoryUsage().heapUsed;
  
  // Simulate extended use
  for (let i = 0; i < 1000; i++) {
    engine.makeChoice(0);
    engine.reset();
  }
  
  // Force garbage collection if available
  if (global.gc) {
    global.gc();
  }
  
  const finalMemory = process.memoryUsage().heapUsed;
  const memoryIncrease = finalMemory - initialMemory;
  
  expect(memoryIncrease).toBeLessThan(10 * 1024 * 1024); // Less than 10MB increase
});

// Use strict TypeScript configuration
// Prefer explicit types over 'any'
// Use meaningful interface and type names

// Good
interface StoryValidationResult {
  isValid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
}

function validateStory(story: QNCEStory): StoryValidationResult {
  // Implementation
}

// Bad
function validate(story: any): any {
  // Implementation
}

// Classes: PascalCase
class QNCEEngine { }
class PerformanceMonitor { }

// Functions: camelCase
function createQNCEEngine() { }
function validateStory() { }

// Constants: SCREAMING_SNAKE_CASE
const DEFAULT_CACHE_SIZE = 100;
const MAX_STORY_NODES = 10000;

// Types/Interfaces: PascalCase
interface QNCEStory { }
type PerformanceMetrics = { }

// Variables: camelCase
const currentNode = engine.getCurrentNode();
const availableChoices = engine.getAvailableChoices();