fn_registry/functions/infra/audit_uses_functions.md

---
name: audit_uses_functions
kind: function
lang: go
domain: infra
version: "1.1.0"
purity: impure
signature: "func AuditUsesFunctions(registryRoot string) ([]UsesFunctionsAudit, error)"
description: "Audita el campo uses_functions de cada app Go y Python registrada en registry.db comparandolo contra los imports reales del codigo fuente. Reporta funciones del registry importadas pero no declaradas (missing_in_app_md) y funciones declaradas pero no detectadas en el codigo (unused_in_app_md). Read-only: no modifica archivos ni la BD."
tags: [doctor, registry-first, audit, imports, uses_functions]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["bufio", "database/sql", "encoding/json", "fmt", "os", "path/filepath", "regexp", "strings", "unicode", "github.com/mattn/go-sqlite3"]
params:
  - name: registryRoot
    desc: "ruta absoluta al directorio raiz del fn_registry (donde vive registry.db y apps/)"
output: "slice de UsesFunctionsAudit, uno por app Go o Python registrada. Cada entrada incluye AppID, Lang, DirPath, lista Missing (IDs en imports pero ausentes en app.md) y lista Unused (IDs en app.md pero no detectados en codigo). Error solo si registry.db no puede abrirse. Apps cuyo dir_path no existe en disco se incluyen con Missing/Unused nil."
tested: true
tests:
  - "missing function detected for Go app"
  - "unused function detected for Go app"
  - "missing dir returns entry with nil slices"
  - "TestAuditUsesFunctions_DetectsNestedImport"
  - "TestAuditUsesFunctions_NoFalsePositiveOnNested"
  - "TestAuditUsesFunctions_StarImport"
test_file_path: "functions/infra/audit_uses_functions_test.go"
file_path: "functions/infra/audit_uses_functions.go"
---

## Ejemplo

```go
results, err := AuditUsesFunctions("$HOME/fn_registry")
if err != nil {
    log.Fatal(err)
}
for _, r := range results {
    if len(r.Missing) > 0 {
        fmt.Printf("[%s] MISSING en app.md: %v\n", r.AppID, r.Missing)
    }
    if len(r.Unused) > 0 {
        fmt.Printf("[%s] UNUSED en app.md: %v\n", r.AppID, r.Unused)
    }
}
```

## Heuristica Go

1. Escanea todos los `.go` de la app buscando `"fn-registry/functions/<domain>"` en imports.
2. Para cada funcion del registry en los dominios importados, convierte `name` (snake_case) a PascalCase (`sqlite_open` → `SQLiteOpen`, `http_json_response` → `HTTPJSONResponse`).
3. Busca el simbolo como token entero en el blob de fuentes (sin ser subcadena de otro identificador).

Abreviaturas reconocidas: HTTP, SQL, URL, API, ID, DB, TLS, JSON, XML, SSH, IO, OK, UI.
Si el nombre exportado real difiere de la convencion (ej. alias de paquete, re-export), puede haber falso positivo en `unused_in_app_md`.

## Heuristica Python

Busca sentencias `from <pkg> import X, Y` en los `.py` de la app y resuelve cada simbolo importado a su ID del registry:

1. **Paquete raiz**: toma el componente anterior al primer punto de `<pkg>` (`metabase.cards` → `metabase`). Solo procesa el import si ese paquete raiz es un directorio de paquete Python del registry (derivado de `file_path`, primer componente bajo `python/functions/`). Imports de librerias externas (`from numpy import array`) se ignoran, evitando falsos `missing`.
2. **Imports anidados**: `from metabase.cards import metabase_get_card` resuelve igual que `from metabase import metabase_get_card`. El simbolo se busca en TODO el paquete (`metabase`), no solo en el submodulo nombrado.
3. **Listas multilinea con parentesis**: `from datascience import (\n  foo,\n  bar,\n)` se parsea entero.
4. **Aliases y comentarios**: `from pkg import foo as bar  # noqa` resuelve la funcion importada (`foo`); el alias local y el comentario se descartan.

El directorio de paquete se deriva de `file_path`, NO del campo `domain`: p.ej. las funciones `metabase` viven en `python/functions/metabase/` pero tienen `domain=infra`.

**No soportado** (fuera de alcance, issue 0056):
- `from <pkg> import *` (star import): se trata como vacio (no cuenta como uso). El registry desaconseja star imports.
- Carga dinamica con `importlib.util.spec_from_file_location(...)` o `import pkg` + `pkg.func()`: no son sentencias `from ... import` estaticas y no se detectan (causa el drift residual en apps como `osint_db`/`osint_web` que cargan funciones via wrapper dinamico).

## Notas

- Read-only: no toca la BD ni archivos.
- Apps cuyo `dir_path` no existe en disco se incluyen con `Missing = nil, Unused = nil` (no se puede inspeccionar el codigo).
- Falsos positivos en `unused_in_app_md`: pueden ocurrir cuando la funcion del registry exporta un nombre no estandar (Go), o cuando una app Python la carga de forma dinamica (`importlib`). Confirmar a mano antes de eliminar de `uses_functions`.
- Falsos negativos (funcion usada no detectada): no ocurren para imports estaticos Python (`from pkg[.sub] import X`, incluido multilinea) ni para imports Go con el patron de nombre estandar, pero si la app hace wrapping o reflexion dinamica la funcion puede pasar desapercibida.

## Capability growth log

- v1.1.0 (2026-06-30) — el parser Python detecta imports anidados (`from pkg.subpkg import X`) y listas multilinea con parentesis; resolucion validada contra el directorio de paquete del registry (derivado de `file_path`), eliminando falsos `unused` en apps que usaban esos patrones (issue 0056).