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 sentenciamatch-- 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 cadenaelif. - 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
defoclassa 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 todoif,try,for,while,withomatch, que ningúndela nivel de módulo elimina, y que ninguna función declaraglobal.
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:
Después:
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:
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).
--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 |