# 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.