79 lines
3.5 KiB
Markdown
79 lines
3.5 KiB
Markdown
---
|
|
id: "0056"
|
|
title: "audit_uses_functions: detectar imports Python anidados (`from pkg.subpkg import X`)"
|
|
status: pendiente
|
|
type: chore
|
|
domain:
|
|
- registry-quality
|
|
scope: registry-only
|
|
priority: media
|
|
depends: []
|
|
blocks: []
|
|
related: []
|
|
created: 2026-05-17
|
|
updated: 2026-05-17
|
|
tags: []
|
|
---
|
|
# 0056 — audit_uses_functions: detectar imports Python anidados (`from pkg.subpkg import X`)
|
|
|
|
## APP Metadata
|
|
|
|
| Campo | Valor |
|
|
|-------|-------|
|
|
| **ID** | 0056 |
|
|
| **Estado** | pendiente |
|
|
| **Prioridad** | media |
|
|
| **Tipo** | enhancement — `functions/infra/audit_uses_functions.go` |
|
|
|
|
## Dependencias
|
|
|
|
- `audit_uses_functions_go_infra` ya existe.
|
|
- `fn doctor uses-functions` lo consume.
|
|
|
|
## Contexto
|
|
|
|
La heuristica actual de Python solo procesa `from <pkg> import <X>` donde `<pkg>` matches `python/functions/{domain}/`. NO maneja:
|
|
|
|
1. `from <pkg>.<subpkg> import <X>` — ej. `from metabase.cards import metabase_get_card`. Resultado: el import se ignora y `metabase_get_card_py_infra` se reporta como `unused_in_app_md`.
|
|
2. `import <pkg>; <pkg>.<symbol>(...)` — uso indirecto.
|
|
|
|
Confirmado en sesion 2026-05-07: `apps/auto_metabase` y `apps/metabase_registry` tienen 8-44 falsos positivos por este motivo. Tras sincronizacion manual quedaron 4/12 apps con drift, todas por esta limitacion.
|
|
|
|
## Objetivo
|
|
|
|
Mejorar el parser Python para detectar imports anidados. Reducir falsos positivos `unused_in_app_md` a 0 en apps Python que usan paquetes anidados del registry.
|
|
|
|
## Arquitectura
|
|
|
|
### Archivos afectados
|
|
|
|
- `functions/infra/audit_uses_functions.go` — bloque que parsea imports Python.
|
|
- `functions/infra/audit_uses_functions_test.go` — anadir test cases.
|
|
- `functions/infra/audit_uses_functions.md` — actualizar `notes` quitando la limitacion.
|
|
|
|
## Tareas
|
|
|
|
### Fase 1 — extender parser de imports Python
|
|
1.1 Aceptar regex `^from\s+(\S+)\s+import\s+(.+)` donde grupo 1 puede contener puntos.
|
|
1.2 Si grupo 1 es `<pkg>` o `<pkg>.<subpkg>` y `<pkg>` matches un dominio Python del registry: para cada simbolo importado en grupo 2, buscar funcion con ese name en el dominio entero (no solo en el subpkg).
|
|
1.3 Soportar `import <pkg> as <alias>` y posterior `<alias>.<func>(...)` — opcional, dejar como mejora futura si complica.
|
|
|
|
### Fase 2 — test cases
|
|
2.1 `TestAuditUsesFunctions_DetectsNestedImport` — fixture con `from metabase.cards import metabase_get_card`. Verificar `metabase_get_card_py_infra` aparece en imports detectados.
|
|
2.2 `TestAuditUsesFunctions_NoFalsePositiveOnNested` — fixture con paquete + subpaquete del registry, ningun unused detectado.
|
|
2.3 `TestAuditUsesFunctions_StarImport` — `from <pkg> import *` debe ignorarse o tratarse como "todo importado" (decision de diseno, documentar).
|
|
|
|
### Fase 3 — verificacion en apps reales
|
|
3.1 Correr `fn doctor uses-functions` post-fix. `apps/auto_metabase` y `apps/metabase_registry` deben quedar sin drift o con drift residual <3 funciones.
|
|
3.2 Update CHANGELOG.md.
|
|
|
|
## Riesgos
|
|
|
|
- Falsos positivos invertidos: si el parser acepta cualquier import como uso, reduce el valor del audit. Mitigacion: solo aceptar imports cuyo paquete raiz mapee a un dominio del registry.
|
|
- Edge case: app importa `from numpy import X` — numpy no es del registry. El parser actual ya lo ignora; mantener.
|
|
|
|
## Decisiones de diseno
|
|
|
|
- NO portar a AST (`ast.parse`) — overkill para este caso. Regex sobre lineas basta y mantiene la funcion auto-contenida sin spawning Python.
|
|
- `from <pkg> import *` se documenta como NO soportado (tratado como vacio). Practica recomendada en el registry: nunca star imports.
|