// @lifecycle canonical - Data-driven step generation utilities.
/**
 * Step Generator
 *
 * Generic utility for generating processing and execution steps from
 * methodology definitions. Works with phase and step data from YAML/JSON
 * to create step sequences and enhancements.
 */

import type { ContentAnalysisResult } from '../../../shared/types/index.js';
import type { PhaseGuard } from '../methodology/methodology-schema.js';
import type {
  ProcessingGuidance,
  StepGuidance,
  ProcessingStep,
  ExecutionStep,
} from '../types/methodology-types.js';

/**
 * Execution step definition from methodology YAML
 */
export interface ExecutionStepDefinition {
  id: string;
  name: string;
  action: string;
  methodologyPhase: string;
  dependencies: string[];
  expected_output: string;
}

/**
 * Template enhancements from phases YAML
 */
export interface TemplateEnhancementsDefinition {
  systemPromptAdditions?: string[];
  userPromptModifications?: string[];
  contextualHints?: string[];
}

/**
 * Execution flow from phases YAML
 */
export interface ExecutionFlowDefinition {
  preProcessingSteps?: string[];
  postProcessingSteps?: string[];
  validationSteps?: string[];
}

/**
 * Execution type enhancements from phases YAML
 */
export interface ExecutionTypeEnhancements {
  chain?: {
    advancedChain?: Record<string, string[]>;
    simpleChain?: Record<string, string[]>;
  };
}

/**
 * Processing step definition from methodology YAML
 */
export interface ProcessingStepDefinition {
  id: string;
  name: string;
  description: string;
  methodologyBasis: string;
  order: number;
  required: boolean;
  /** Section header for detection (e.g., "## Context") */
  section_header?: string;
  /** Deterministic phase guards evaluated against the section under this header */
  guards?: PhaseGuard;
}

/**
 * Phases definition from methodology YAML
 */
export interface PhasesDefinition {
  processingSteps?: ProcessingStepDefinition[];
  executionSteps?: ExecutionStepDefinition[];
  templateEnhancements?: TemplateEnhancementsDefinition;
  executionFlow?: ExecutionFlowDefinition;
  executionTypeEnhancements?: ExecutionTypeEnhancements;
}

/**
 * Converts processing step definitions to ProcessingStep format
 * @param steps - Processing step definitions from YAML
 * @returns Array of ProcessingStep objects sorted by order
 */
export function generateProcessingSteps(steps: ProcessingStepDefinition[]): ProcessingStep[] {
  return [...steps]
    .sort((a, b) => a.order - b.order)
    .map((step) => ({
      id: step.id,
      name: step.name,
      description: step.description,
      methodologyBasis: step.methodologyBasis,
      order: step.order,
      required: step.required,
      ...(step.section_header && { section_header: step.section_header }),
      ...(step.guards && { guards: step.guards }),
    }));
}

/**
 * Converts execution step definitions to ExecutionStep format
 * @param steps - Execution step definitions from YAML
 * @returns Array of ExecutionStep objects
 */
export function generateExecutionSteps(steps: ExecutionStepDefinition[]): ExecutionStep[] {
  return steps.map((step) => ({
    id: step.id,
    name: step.name,
    action: step.action,
    methodologyPhase: step.methodologyPhase,
    dependencies: step.dependencies || [],
    expected_output: step.expected_output,
  }));
}

/**
 * Creates ProcessingGuidance from phases definition
 * @param phases - Phases definition from YAML
 * @param _template - Template being processed (for future analysis)
 * @param _executionType - Execution type from semantic analyzer
 * @returns ProcessingGuidance object
 */
export function createProcessingGuidance(
  phases: PhasesDefinition,
  _template = '',
  _executionType = 'single'
): ProcessingGuidance {
  // #todo: Wire processingSteps into prompt_guidance as authoring checklists/template hints; also feed into validation/analytics for missing coverage.
  const processingSteps = phases.processingSteps
    ? generateProcessingSteps(phases.processingSteps)
    : [];

  const templateEnhancements = phases.templateEnhancements ?? {};
  const executionFlow = phases.executionFlow ?? {};

  return {
    processingSteps,
    templateEnhancements: {
      systemPromptAdditions: templateEnhancements.systemPromptAdditions ?? [],
      userPromptModifications: templateEnhancements.userPromptModifications ?? [],
      contextualHints: templateEnhancements.contextualHints ?? [],
    },
    executionFlow: {
      preProcessingSteps: executionFlow.preProcessingSteps ?? [],
      postProcessingSteps: executionFlow.postProcessingSteps ?? [],
      validationSteps: executionFlow.validationSteps ?? [],
    },
  };
}

/**
 * Creates StepGuidance from phases definition with semantic analysis
 * @param phases - Phases definition from YAML
 * @param semanticAnalysis - Semantic analysis result
 * @returns StepGuidance object
 */
export function createStepGuidance(
  phases: PhasesDefinition,
  semanticAnalysis?: ContentAnalysisResult
): StepGuidance {
  // #todo: Expose executionSteps via a “methodology_steps” toolcall (akin to %judge) so the client LLM can request structured steps for the user query; currently guidance-only.
  const executionSteps = phases.executionSteps ? generateExecutionSteps(phases.executionSteps) : [];

  const stepEnhancements: Record<string, string[]> = {};
  const stepValidation: Record<string, string[]> = {};

  // Apply execution type-specific enhancements based on semantic analysis
  if (semanticAnalysis && phases.executionTypeEnhancements?.chain) {
    const chainEnhancements = phases.executionTypeEnhancements.chain;

    if (
      semanticAnalysis.executionType === 'chain' &&
      semanticAnalysis.executionCharacteristics.advancedChainFeatures?.requiresAdvancedExecution &&
      chainEnhancements.advancedChain
    ) {
      // Apply advanced chain enhancements
      for (const [stepId, enhancements] of Object.entries(chainEnhancements.advancedChain)) {
        stepEnhancements[stepId] = enhancements;
        stepValidation[stepId] = [
          'Workflow completeness check',
          'State transition validation',
          'Error handling verification',
        ];
      }
    } else if (semanticAnalysis.executionType === 'chain' && chainEnhancements.simpleChain) {
      // Apply simple chain enhancements
      for (const [stepId, enhancements] of Object.entries(chainEnhancements.simpleChain)) {
        stepEnhancements[stepId] = enhancements;
        stepValidation[stepId] = [
          'Step sequence validation',
          'Data flow verification',
          'Checkpoint adequacy assessment',
        ];
      }
    }
  }

  return {
    stepSequence: executionSteps,
    stepEnhancements,
    stepValidation,
  };
}
