Saltar a contenido

Reglas de Refactorización

complexipy incluye un sistema de refactorización inspirado en clippy que proporciona sugerencias accionables para reducir la complejidad cognitiva. Cada regla tiene un ID único, categoría y nivel de aplicabilidad.

Categorías de Reglas

Categoría Icono Descripción
Complejidad ▲ Reglas que reducen directamente la complejidad cognitiva
Legibilidad ◆ Reglas que mejoran la legibilidad del código

Niveles de Aplicabilidad

Nivel Icono Descripción
Seguro de aplicar * Alta confianza en que el código generado es correcto tal cual
Necesita revisión ! Suele ser correcto, con formas de fallo conocidas, por lo que una persona debe revisarlo
Informativo i Solo orientación, no es directamente accionable

El nivel decide cómo una herramienta puede aplicar la sugerencia:

  • Seguro de aplicar: la aplicación automática (--fix, correcciones del editor) puede aplicar la sugerencia directamente, cuando el reemplazo es también un empalme fiel (spliceable).
  • Necesita revisión: la aplicación automática rechaza la sugerencia salvo que la autorices de forma explícita.
  • Informativo: nada edita el código por esta sugerencia.

Hoy ninguna regla usa Necesita revisión. El nivel queda reservado para una sugerencia que suele ser correcta pero cambia el comportamiento en una forma de entrada conocida, y una regla solo puede usarlo con pruebas para cada forma de fallo conocida.

--fix aplica una sugerencia solo en Seguro de aplicar y solo cuando el reemplazo es un empalme fiel. C005 es un empalme solo cuando cada nombre que lee su condición conserva su valor dentro de un helper a nivel de módulo (ver Cómo aplica --fix C005); si no, su sugerencia queda para aplicación manual.

Suprimir una Regla

Cada id de regla se puede desactivar para un proyecto o para una función. Usa --ignore C007 (o ignore = ["C007"] en complexipy.toml) para un proyecto, y # complexipy: ignore[C007] junto a una función para una función. --select C001,C007 conserva solo las reglas nombradas. Un nombre de grupo elige todas las reglas de esa categoría: --ignore readability oculta C005 y C007. Una regla inactiva nunca aparece en ninguna salida. Ver Selección de Reglas.

Ejecuta complexipy --explain C007 para imprimir la categoría, la aplicabilidad, la descripción y el enlace a la sección de una regla en esta página.


Reglas de Complejidad

C001: Aplanar Condiciones Anidadas

  • Categoría: ▲ Complejidad
  • Aplicabilidad: i Informativo
  • Prioridad: Alta (4/5)

Aplana bloques de condiciones anidadas usando cláusulas de guarda con retornos anticipados.

¿Cuándo se activa?

Esta regla se activa cuando una función tiene sentencias if profundamente anidadas (2+ niveles de anidamiento) que añaden complejidad significativa.

Ejemplo

Antes:

def process_data(data):
    if data:
        if data.is_valid():
            if data.is_ready():
                return process(data)
    return None

Después:

def process_data(data):
    if not data:
        return None
    if not data.is_valid():
        return None
    if not data.is_ready():
        return None
    return process(data)

Por qué esto ayuda

Las condiciones profundamente anidadas son difíciles de seguir. Usar cláusulas de guarda con retornos anticipados reduce la carga cognitiva al mantener la ruta principal en un nivel de indentación menor.


C002: Guardas de Bucles

  • Categoría: ▲ Complejidad
  • Aplicabilidad: * Seguro de aplicar
  • Prioridad: Media (3/5)

Usa guardas continue al inicio de los bucles para reducir el anidamiento.

¿Cuándo se activa?

Esta regla se activa cuando un bucle contiene sentencias if anidadas que podrían convertirse en guardas continue anticipadas.

Solo se ofrece un reemplazo cuando el if anidado es la última sentencia del cuerpo del bucle. Si le siguen otras sentencias, una guarda las omitiría, así que la regla da un texto de ayuda en su lugar.

Ejemplo

Antes:

def process_items(items):
    total = 0
    for item in items:
        if item.active:
            if item.ready:
                total += item.value
    return total

Después:

def process_items(items):
    total = 0
    for item in items:
        if not item.active:
            continue
        if not item.ready:
            continue
        total += item.value
    return total

Cada guarda niega su condición como lo espera un linter: x in y pasa a x not in y, a is b pasa a a is not b, un not inicial desaparece, y un nombre o una llamada recibe un not sin paréntesis. El not conserva los paréntesis alrededor de and, or, otras comparaciones, expresiones condicionales, lambdas y asignaciones walrus.

Por qué esto ayuda

Las condiciones anidadas dentro de los bucles añaden indentación innecesaria. Usar guardas continue mantiene la lógica principal en un nivel de anidamiento menor y hace que el bucle sea más fácil de seguir.


C003: Extraer Función Auxiliar

  • Categoría: ▲ Complejidad
  • Aplicabilidad: i Informativo
  • Prioridad: Baja (2/5)

Extrae bloques de código complejos en funciones auxiliares separadas.

¿Cuándo se activa?

Esta regla se activa cuando un bloque de código tiene alta complejidad (6+) y abarca múltiples líneas (5+).

Ejemplo

Antes:

def process_order(order):
    # Complex validation and processing logic
    if order.items:
        for item in order.items:
            if item.quantity > 0:
                if item.price > 0:
                    total = item.quantity * item.price
                    if total > 100:
                        apply_discount(total)
                    process_item(item)

Después:

def process_order(order):
    if not order.items:
        return
    for item in order.items:
        process_order_item(item)

def process_order_item(item):
    if item.quantity <= 0 or item.price <= 0:
        return
    total = item.quantity * item.price
    if total > 100:
        apply_discount(total)
    process_item(item)

Por qué esto ayuda

Los bloques de código complejos deben extraerse en funciones con nombre para mejorar la legibilidad y la capacidad de prueba. La función extraída puede recibir un nombre descriptivo que explique su propósito.


C004: Dividir Despachador

  • Categoría: ▲ Complejidad
  • Aplicabilidad: i Informativo
  • Prioridad: Baja (2/5)

Divide cadenas largas de elif en manejadores separados.

¿Cuándo se activa?

Esta regla se activa cuando una cadena if/elif tiene 3+ ramas. Las sentencias match se excluyen intencionalmente: el modelo de complejidad cognitiva de complexipy asigna a un match un costo fijo sin importar cuántas cláusulas case tenga (a diferencia de una cadena elif, donde cada rama adicional suma a la puntuación), así que dividir un match en manejadores separados no reduciría realmente la complejidad medida.

El refactor sugerido depende de la forma de la cadena:

  • Si todas las ramas comparan la misma variable contra un literal con ==, la cadena puede convertirse en una sentencia match -- esto se recomienda por encima de un diccionario de despacho, ya que no necesita indirección adicional y el propio modelo de complexipy la puntúa sin el costo por rama que tiene la cadena elif.
  • En caso contrario (rangos, varias variables, comparaciones que no son de igualdad -- cualquier cosa que un simple match case <valor>: no pueda expresar), se sugiere en su lugar un diccionario de despacho que asigna casos a funciones manejadoras.

Ejemplo: igualdad de una sola variable → match

Antes:

def handle_action(action):
    if action == "create":
        return create_resource()
    elif action == "read":
        return read_resource()
    elif action == "update":
        return update_resource()
    elif action == "delete":
        return delete_resource()
    return None

Después:

def handle_action(action):
    match action:
        case "create":
            return create_resource()
        case "read":
            return read_resource()
        case "update":
            return update_resource()
        case "delete":
            return delete_resource()
    return None

Ejemplo: rangos → diccionario de despacho

Antes:

def classify(score):
    if score < 60:
        return "fail"
    elif score < 70:
        return "d"
    elif score < 85:
        return "b"
    elif score < 95:
        return "a"
    return "a+"

Después:

def classify(score):
    thresholds = [(60, "fail"), (70, "d"), (85, "b"), (95, "a")]
    for limit, grade in thresholds:
        if score < limit:
            return grade
    return "a+"

Por qué esto ayuda

Las cadenas condicionales largas son difíciles de mantener y extender. Dividirlas en manejadores separados -- una sentencia match cuando la cadena es un despacho simple por igualdad, un diccionario de despacho en caso contrario -- hace que cada caso sea independientemente testeable y la lógica de despacho más clara.


C011: Aplanar Try/Except

  • Categoría: ▲ Complejidad
  • Aplicabilidad: i Informativo
  • Prioridad: Baja (2/5)

Aplana bloques try/except anidados combinándolos o reestructurándolos.

¿Cuándo se activa?

Esta regla se activa cuando los bloques try/except están anidados unos dentro de otros.

Ejemplo

Antes:

def read_config(path):
    try:
        with open(path) as f:
            try:
                return json.load(f)
            except json.JSONDecodeError:
                return default_config()
    except FileNotFoundError:
        return default_config()

Después:

def read_config(path):
    try:
        with open(path) as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError):
        return default_config()

Por qué esto ayuda

Los bloques try/except anidados son confusos y difíciles de mantener. Considera fusionarlos o extraer el bloque interno en una función separada con su propio manejo de errores.


Reglas de Legibilidad

C005: Extraer Predicado

  • Categoría: ◆ Legibilidad
  • Aplicabilidad: * Seguro de aplicar
  • Prioridad: Baja (2/5)

Extrae condiciones booleanas complejas en funciones predicado con nombre.

¿Cuándo se activa?

Esta regla se activa cuando una condición booleana contiene 2+ operadores lógicos (and, or, not).

La sugerencia conserva la palabra clave de la sentencia: una condición if sigue siendo if, una condición while sigue siendo while. Las condiciones en líneas elif solo reciben texto de ayuda, porque una función extraída no puede colocarse dentro de una cadena if.

El helper extraído se emite a nivel de módulo con las variables libres de la condición como parámetros (bases de atributos incluidas, builtins excluidas), de modo que es testeable por unidad. El fragmento muestra el contexto que lo rodea en la indentación real de la sentencia, con marcadores ... para las sentencias omitidas. Las condiciones que vinculan un nombre con := o contienen un lambda/comprensión reciben solo texto de ayuda.

Cómo aplica --fix C005

La corrección hace dos ediciones. Inserta el helper antes del def o class a nivel de módulo que contiene la función, decoradores incluidos, y reescribe la línea de cabecera de la condición como una llamada al helper. La sugerencia lleva el helper en insertions y la línea de cabecera en replacement, y su reducción se mide.

La llamada pasa cada variable libre de forma inmediata, mientras que la condición original puede saltarse algunas por cortocircuito. Por eso --fix aplica C005 solo cuando cada nombre está vinculado con seguridad:

  • un parámetro que la función nunca vuelve a vincular;
  • un builtin que ni la función, ni sus parámetros, ni el módulo vinculan;
  • el nombre del def o class a nivel de módulo que contiene la función, o un global que una sentencia a nivel de módulo vincula encima de la función, fuera de todo if, try, for, while, with o match, que ningún del a nivel de módulo elimina, y que ninguna función declara global.

Cualquier otro nombre conserva el fragmento para aplicación manual, con spliceable: false. Lo mismo ocurre con una condición dentro de una función o clase anidada, una función bajo una sentencia compuesta a nivel de módulo, una cabecera que ocupa varias líneas, y una condición que contiene super(), __class__, un __nombre privado, await o yield.

Ejemplo

Antes:

def is_eligible(user, order):
    if (user.is_active and user.has_subscription) or (order.total > 100 and not order.is_gift):
        return True
    return False

Después:

def is_eligible(user, order):
    return has_active_subscription(user) or is_qualifying_order(order)

def has_active_subscription(user):
    return user.is_active and user.has_subscription

def is_qualifying_order(order):
    return order.total > 100 and not order.is_gift

Por qué esto ayuda

Las expresiones booleanas complejas son difíciles de entender a simple vista. Extraerlas en predicados con nombre hace que el código sea autoexplicativo y más fácil de probar.


C007: Aplanar If Anidados

  • Categoría: ◆ Legibilidad
  • Aplicabilidad: * Seguro de aplicar
  • Prioridad: Máxima (5/5)

Combina sentencias if anidadas en un único if con las condiciones combinadas.

¿Cuándo se activa?

Esta regla se activa cuando el cuerpo completo de una sentencia if es un único if anidado sin rama else, para una cadena de dos o más niveles de este tipo.

La fusión se omite cuando hay alguna sentencia o comentario entre el if exterior y el interior, de modo que la sugerencia nunca elimina código.

Un comentario en una de las líneas if fusionadas, como # type: ignore, pasa a la línea fusionada. Cuando dos o más de esas líneas tienen un comentario, o el if interior tiene su cuerpo en la misma línea, la regla da un texto de ayuda en lugar de un reemplazo.

Ejemplo

Antes:

def check_eligibility(user):
    if user.is_active:
        if user.has_permission:
            return True
    return False

Después:

def check_eligibility(user):
    if user.is_active and user.has_permission:
        return True
    return False

Por qué esto ayuda

Las sentencias if anidadas con un único cuerpo pueden combinarse en un único if con las condiciones unidas mediante and. Esto reduce el anidamiento y mejora la legibilidad.


Uso de las Reglas de Refactorización

Sugerencias de Refactorización

Usa --suggest-refactors para imprimir un conjunto pequeño y ordenado de planes deterministas de refactorización junto a los resultados enriquecidos de la CLI:

complexipy . --failed --suggest-refactors

Salida de ejemplo (abreviada -- la salida real también muestra un tramo subrayado con acentos circunflejos, el código fuente circundante y un enlace a la documentación):

      [1] C007 Merge nested if statements
          --> sample.py:4:9
          Category: ◆ Readability | Applicability: * Safe to apply
          Lines 4-6 -> Estimated reduction: -2 complexity (6 -> 4)

          Suggestion: * Safe to apply
          Merge nested conditions into `if item.active and item.ready:`

Los planes se basan solo en el análisis AST de Rust; no se usa IA y no se reescribe código automáticamente. Las reducciones estimadas son aproximadas, ordenadas y limitadas, así que trátalas como orientación, no como puntuaciones futuras exactas. --plain --suggest-refactors imprime una línea por plan: id de regla, título y reducción.

Aplicar Sugerencias Aplicables

Usa --fix para escribir las sugerencias aplicables en los archivos fuente. Una sugerencia es aplicable cuando su aplicabilidad es Seguro de aplicar y su reemplazo es un empalme fiel ("spliceable": true en la salida JSON). Eso cubre C002 (guardas de bucle), C007 (if plegable) y C005 (extraer predicado) cuando cada nombre que lee su condición conserva su valor dentro de un helper a nivel de módulo. Para C005 la corrección también inserta el helper encima de la función (ver Cómo aplica --fix C005).

complexipy . --fix

--fix solo cambia funciones cuya complejidad supera max-complexity-allowed, la misma regla que usa el control. Cada paso vuelve a comprobar el umbral, así que una función deja de cambiar en cuanto lo cumple. Una función en el umbral o por debajo conserva sus sugerencias en el reporte y nunca se reescribe. Una ejecución aplica cada plan aplicable de esas funciones en cada archivo analizado y repite paso a paso, hasta 8 pasos, hasta que no quede ningún plan aplicable; un paso posterior etiqueta su diff como pass 2:. Por cada archivo corregido, la ejecución imprime un diff unificado con resaltado de sintaxis de los cambios aplicados, con números de línea, una línea de contexto por bloque y la regla que se activó, y luego un resumen de las correcciones aplicadas y omitidas. El resumen muestra la reducción de cada corrección como (-3 complexity), con una tilde delante del número ((- ~3 complexity)) cuando el número es estimado. Las líneas del resumen usan los números de línea del archivo anteriores a la ejecución, en cada paso; una corrección dentro de una región que un paso anterior reescribió informa las líneas de esa región. Cuando no hay nada aplicable, la ejecución imprime No fixes to apply. El reporte y cada control miden el estado después de las correcciones. Reanalizar un archivo corregido muestra que el hallazgo desapareció y que la complejidad bajó en la reducción medida del plan.

--fix --dry-run previsualiza los mismos cambios: imprime solo el diff unificado y no escribe nada, ni siquiera la caché o el snapshot. --fix se ejecuta donde estés: los cambios sin confirmar, los archivos sin rastrear y la ausencia de un repositorio de git nunca lo bloquean, y no hace falta ninguna flag extra. Una corrección conserva los finales de línea del archivo y su salto de línea final. El filtrado por regla se apoya en --select e --ignore.

--fix reescribe solo archivos regulares dentro del directorio desde el que se ejecuta. Omite un enlace simbólico y un archivo que cambió en disco después de que complexipy lo leyera. Escribe un archivo nuevo junto al original y lo renombra en su lugar, conservando los bits de permisos y el grupo, pero no setuid, setgid, los atributos extendidos ni las ACL.

Estructura de Salida JSON:

[
    {
        "path": "src/main.py",
        "file_name": "main.py",
        "function_name": "process_data",
        "complexity": 6,
        "line_start": 1,
        "line_end": 7,
        "line_complexities": [
            {"line": 3, "complexity": 1},
            {"line": 4, "complexity": 2},
            {"line": 5, "complexity": 3}
        ],
        "refactor_plans": [
            {
                "rule_id": "C007",
                "kind": "collapsible_if",
                "title": "Merge nested if statements",
                "line_start": 4,
                "line_end": 6,
                "column_start": 9,
                "current_complexity": 6,
                "estimated_reduction": 2,
                "estimated_complexity_after": 4,
                "reduction_is_measured": true,
                "category": "Readability",
                "applicability": "MachineApplicable",
                "description": "Merge nested if statements into a single if with combined conditions",
                "explanation": "Nested if statements with a single body can be merged into a single if with combined conditions using 'and'. This reduces nesting and improves readability.",
                "references": [],
                "suggestion": {
                    "replacement": "        if item.active and item.ready:\n            total += item.value",
                    "applicability": "MachineApplicable",
                    "spliceable": true,
                    "insertions": [],
                    "description": "Merge nested conditions into `if item.active and item.ready:`"
                },
                "help": null,
                "doc_url": "https://complexipy.com/refactoring-rules/#c007-collapsible-if"
            }
        ]
    }
]

La salida JSON contiene una entrada por cada función emitida. La lista refactor_plans solo se completa cuando también se pasa --suggest-refactors -- de lo contrario es [], igual que el comportamiento de la salida enriquecida de la CLI. La salida CSV no incluye planes, y una celda que una hoja de cálculo ejecutaría como fórmula (una que empieza con =, +, - o @) se escribe con un ' inicial. Cada entrada JSON incluye line_start y line_end de la función, y line_complexities: las líneas que suman a la puntuación, una entrada por línea en orden de línea, cuyos valores de complexity suman la complexity de la función. La salida CSV no incluye datos de líneas.

Línea de Comandos

# Muestra sugerencias de refactorización
complexipy . --suggest-refactors

# Muestra sugerencias solo para las funciones que fallan
complexipy . --failed --suggest-refactors

# Exporta sugerencias a JSON
complexipy . --output-format json --suggest-refactors

API de Python

from complexipy import code_complexity

code = """
def process(data):
    if data:
        if data.is_valid():
            return process(data)
    return None
"""

result = code_complexity(code)
for func in result.functions:
    for plan in func.refactor_plans:
        print(f"[{plan.rule_id}] {plan.title}")
        print(f"  Category: {plan.category}")
        print(f"  Applicability: {plan.applicability}")
        print(f"  Reduction: -{plan.estimated_reduction} complexity")
        if plan.suggestion:
            print(f"  Suggested replacement:\n{plan.suggestion.replacement}")
        elif plan.help:
            print(f"  Help: {plan.help}")
        print(f"  Docs: {plan.doc_url}")

Salida JSON

La salida JSON incluye todos los metadatos de las reglas para consumo programático:

{
  "rule_id": "C007",
  "kind": "collapsible_if",
  "title": "Merge nested if statements",
  "category": "Readability",
  "applicability": "MachineApplicable",
  "description": "Merge nested if statements into a single if with combined conditions",
  "line_start": 3,
  "line_end": 5,
  "column_start": 5,
  "current_complexity": 4,
  "estimated_reduction": 1,
  "estimated_complexity_after": 3,
  "reduction_is_measured": true,
  "suggestion": {
    "replacement": "    if data and data.is_valid():\n        return process(data)",
    "applicability": "MachineApplicable",
    "spliceable": true,
    "insertions": [],
    "description": "Merge nested conditions into `if data and data.is_valid():`"
  },
  "help": null,
  "explanation": "Nested if statements with a single body can be merged into a single if with combined conditions using 'and'. This reduces nesting and improves readability.",
  "references": [],
  "doc_url": "https://complexipy.com/refactoring-rules/#c007-collapsible-if"
}

Reducciones medidas vs estimadas

Cada plan informa cuánto reduce la complejidad al aplicarlo (estimated_reduction / estimated_complexity_after) junto con un indicador de confianza, reduction_is_measured:

  • Medida (true): la regla insertó su sugerencia en el código real, lo re-analizó y volvió a ejecutar el puntuador. El número es la respuesta literal a "aplica esto y vuelve a puntuar" - exactamente lo que reportan C002, C007 y un C005 empalmable, que llevan reemplazos aplicables por máquina. La CLI los muestra sin calificador: Reduction: -2 complexity (7 -> 5).
  • Estimada (false): el número proviene de la fórmula manual de la regla (reglas solo con ayuda C001, C003, C004, C011, un fragmento C005 no empalmable, además de cualquier respaldo cuando una inserción no se puede re-analizar). La CLI los muestra con una tilde: Estimated reduction: ~-2 complexity (7 -> 5).

Una reducción medida de 0 significa que la sugerencia no reduce la complejidad realmente; el plan se descarta en lugar de mostrarse.


Referencia de IDs de Reglas

ID Nombre Categoría Aplicabilidad Prioridad
C001 Aplanar Condiciones Anidadas ▲ Complejidad i Informativo Alta
C002 Guardas de Bucles ▲ Complejidad * Seguro de aplicar Media
C003 Extraer Función Auxiliar ▲ Complejidad i Informativo Baja
C004 Dividir Despachador ▲ Complejidad i Informativo Baja
C005 Extraer Predicado ◆ Legibilidad * Seguro de aplicar Baja
C007 Aplanar If Anidados ◆ Legibilidad * Seguro de aplicar Máxima
C011 Aplanar Try/Except ▲ Complejidad i Informativo Baja