// NOTE: This block replaces the previous import block to ensure types/interfaces are defined correctly.
import { OpenAPIV3 } from 'openapi-types';
import { RenderContext, RenderResultItem } from './types.js'; // Add .js
import {
  buildComponentDetailUriSuffix,
  buildComponentMapUriSuffix,
  buildOperationUriSuffix,
  // buildPathItemUriSuffix, // Not currently used by generateListHint
} from '../utils/uri-builder.js'; // Added .js extension

// Define possible types for list items to guide hint generation
type ListItemType = 'componentType' | 'componentName' | 'pathMethod';

// Define context needed for generating the correct detail URI suffix
interface HintContext {
  itemType: ListItemType;
  firstItemExample?: string; // Example value from the first item in the list
  // For componentName hints, the parent component type is needed
  parentComponentType?: string;
  // For pathMethod hints, the parent path is needed
  parentPath?: string;
}

/**
 * Safely retrieves the summary from an Operation object.
 * Handles cases where the operation might be undefined or lack a summary.
 *
 * @param operation - The Operation object or undefined.
 * @returns The operation summary or operationId string, truncated if necessary, or null if neither is available.
 */
export function getOperationSummary(
  operation: OpenAPIV3.OperationObject | undefined
): string | null {
  // Return summary or operationId without truncation
  return operation?.summary || operation?.operationId || null;
}

/**
 * Helper to generate a standard hint text for list views, using the centralized URI builders.
 * @param renderContext - The rendering context containing the base URI.
 * @param hintContext - Context about the type of items being listed and their parent context.
 * @returns The hint string.
 */
export function generateListHint(renderContext: RenderContext, hintContext: HintContext): string {
  let detailUriSuffixPattern: string;
  let itemTypeName: string; // User-friendly name for the item type in the hint text
  let exampleUriSuffix: string | undefined; // To hold the generated example URI

  switch (hintContext.itemType) {
    case 'componentType':
      // Listing component types (e.g., schemas, responses) at openapi://components
      // Hint should point to openapi://components/{type}
      detailUriSuffixPattern = buildComponentMapUriSuffix('{type}'); // Use placeholder
      itemTypeName = 'component type';
      if (hintContext.firstItemExample) {
        exampleUriSuffix = buildComponentMapUriSuffix(hintContext.firstItemExample);
      }
      break;
    case 'componentName':
      // Listing component names (e.g., MySchema, User) at openapi://components/{type}
      // Hint should point to openapi://components/{type}/{name}
      if (!hintContext.parentComponentType) {
        console.warn('generateListHint called for componentName without parentComponentType');
        return ''; // Avoid generating a broken hint
      }
      // Use the actual parent type and a placeholder for the name
      detailUriSuffixPattern = buildComponentDetailUriSuffix(
        hintContext.parentComponentType,
        '{name}'
      );
      itemTypeName = hintContext.parentComponentType.slice(0, -1); // e.g., 'schema' from 'schemas'
      if (hintContext.firstItemExample) {
        exampleUriSuffix = buildComponentDetailUriSuffix(
          hintContext.parentComponentType,
          hintContext.firstItemExample
        );
      }
      break;
    case 'pathMethod':
      // Listing methods (e.g., get, post) at openapi://paths/{path}
      // Hint should point to openapi://paths/{path}/{method}
      if (!hintContext.parentPath) {
        console.warn('generateListHint called for pathMethod without parentPath');
        return ''; // Avoid generating a broken hint
      }
      // Use the actual parent path and a placeholder for the method
      detailUriSuffixPattern = buildOperationUriSuffix(hintContext.parentPath, '{method}');
      itemTypeName = 'operation'; // Or 'method'? 'operation' seems clearer
      if (hintContext.firstItemExample) {
        // Ensure the example method is valid if needed, though usually it's just 'get', 'post' etc.
        exampleUriSuffix = buildOperationUriSuffix(
          hintContext.parentPath,
          hintContext.firstItemExample
        );
      }
      break;
    default:
      // Explicitly cast to string to avoid potential 'never' type issue in template literal
      console.warn(`Unknown itemType in generateListHint: ${String(hintContext.itemType)}`);
      return ''; // Avoid generating a hint if context is unknown
  }

  // Construct the full hint URI pattern using the base URI
  const fullHintPattern = `${renderContext.baseUri}${detailUriSuffixPattern}`;
  const fullExampleUri = exampleUriSuffix
    ? `${renderContext.baseUri}${exampleUriSuffix}`
    : undefined;

  let hintText = `\nHint: Use '${fullHintPattern}' to view details for a specific ${itemTypeName}.`;
  if (fullExampleUri) {
    hintText += ` (e.g., ${fullExampleUri})`;
  }

  return hintText;
}

/**
 * Helper to generate a standard error item for RenderResultItem arrays.
 * @param uriSuffix - The URI suffix for the error context.
 * @param message - The error message.
 * @returns A RenderResultItem array containing the error.
 */
export function createErrorResult(uriSuffix: string, message: string): RenderResultItem[] {
  return [
    {
      uriSuffix: uriSuffix,
      data: null,
      isError: true,
      errorText: message,
      renderAsList: true, // Errors are typically plain text
    },
  ];
}