13. Autocompletado en Vivo (Ghost Text), Comentarios Guía e Inline Chat (Ctrl+I)

/**
 * EJEMPLO DE MAL COMENTARIO (Ambiguo -> genera código pobre):
 * // calcular descuento
 */

/**
 * EJEMPLO DE COMENTARIO PROFESIONAL PARA COPILOT (Específico y con casos borde):
 * Calcula el precio final de una orden aplicando descuentos escalonados e IVA.
 * Reglas:
 * 1. Si subtotal <= 0 o ivaPorcentaje < 0, lanzar TypeError.
 * 2. Si el cupón es "KILO20", aplicar 20% de descuento; si es "KILO10", aplicar 10%.
 * 3. Redondear el resultado final a 2 decimales numéricos.
 *
 * @param {number} subtotal
 * @param {string|null} cupon
 * @param {number} ivaPorcentaje (ej. 19 para 19%)
 * @returns {number}
 */
function calcularTotalOrden(subtotal, cupon = null, ivaPorcentaje = 19) {
  // Al presionar Enter aquí, GitHub Copilot leerá las 3 reglas de arriba
  // y sugerirá automáticamente el bloque completo validado:
  if (typeof subtotal !== "number" || subtotal <= 0 || ivaPorcentaje < 0) {
    throw new TypeError("El subtotal debe ser mayor a cero y el IVA no negativo.");
  }

  let descuento = 0;
  if (cupon === "KILO20") {
    descuento = 0.20;
  } else if (cupon === "KILO10") {
    descuento = 0.10;
  }

  const baseConDescuento = subtotal * (1 - descuento);
  const totalConIva = baseConDescuento * (1 + ivaPorcentaje / 100);

  return Math.round(totalConIva * 100) / 100;
}