fn_registry/.claude/CLAUDE.md

fn-registry

Registry personal de codigo reutilizable con busqueda FTS. Diseñado para composicion funcional y agentes.

Explorar el registry (USAR SIEMPRE)

La BD SQLite registry.db es tu mapa del repositorio. Antes de escribir codigo, SIEMPRE consultala para saber que existe, evitar duplicados y descubrir funciones reutilizables.

# Buscar funciones por texto libre (FTS5)
sqlite3 registry.db "SELECT id, kind, purity, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'slice') ORDER BY name;"

# Listar todas las funciones de un dominio
sqlite3 registry.db "SELECT id, purity, signature FROM functions WHERE domain = 'finance' ORDER BY name;"

# Listar solo puras de un dominio
sqlite3 registry.db "SELECT id, signature FROM functions WHERE domain = 'core' AND purity = 'pure' ORDER BY name;"

# Listar solo impuras
sqlite3 registry.db "SELECT id, domain, error_type FROM functions WHERE purity = 'impure' ORDER BY domain, name;"

# Buscar tipos por dominio
sqlite3 registry.db "SELECT id, algebraic, description FROM types WHERE domain = 'cybersecurity';"

# Ver que funciones usa un pipeline o funcion compuesta
sqlite3 registry.db "SELECT id, uses_functions, uses_types FROM functions WHERE uses_functions != '[]';"

# Ver funciones que dependen de un tipo concreto
sqlite3 registry.db "SELECT id FROM functions WHERE uses_types LIKE '%ohlcv_go_finance%';"

# Buscar por tag
sqlite3 registry.db "SELECT id, tags FROM functions WHERE tags LIKE '%generic%';"

# Contar entradas por dominio
sqlite3 registry.db "SELECT domain, COUNT(*) FROM functions GROUP BY domain;"

# Ver todo el schema
sqlite3 registry.db ".schema"

La BD usa WAL mode — puedes leerla mientras se escribe sin bloqueos.

Estructura del repositorio

fn-registry/
  functions/            # Codigo y docs de funciones
    core/               # Utilidades genericas (filter, map, pipeline, retry...)
    finance/            # Indicadores, riesgo, IO de mercado
    datascience/        # Estadistica, DSP, IO de datos
    cybersecurity/      # Crypto, analisis de red, IO de seguridad
    pipelines/          # Composiciones de funciones, siempre impuras
    components/         # Componentes React (.tsx)
  types/                # Tipos algebraicos (product y sum)
    core/               # Result, Option, Pair, Error
    finance/            # OHLCV, Tick, BollingerResult, DrawdownResult
    datascience/        # OutlierResult
    cybersecurity/      # CIDRBlock, ThreatResult, PortResult
  registry/             # Libreria Go: modelos, SQLite, parser, indexer, validacion
  cmd/fn/               # CLI
  docs/                 # Schema de documentacion v1.0 (fuente de verdad del diseño)
  docs/templates/       # Plantillas de frontmatter para function, pipeline, component, type
  registry.db           # Indice SQLite FTS5+WAL (regenerable, NO commitear)

Build

CGO_ENABLED=1 go build -tags fts5 ./...
CGO_ENABLED=1 go test -tags fts5 ./...
CGO_ENABLED=1 go build -tags fts5 -o fn ./cmd/fn/

Reglas para añadir funciones nuevas

Antes de crear

1. Consulta la BD para verificar que no existe algo similar:

   sqlite3 registry.db "SELECT id, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'tu busqueda');"
   

2. Identifica el dominio correcto: core, finance, datascience, cybersecurity, o crea uno nuevo si no encaja
3. Decide la purity: pure si no tiene side effects, impure si tiene IO/estado/goroutines/tiempo

Archivos a crear

Cada funcion requiere EXACTAMENTE dos archivos:

1. Implementacion functions/{domain}/{name}.go — codigo real, compilable
2. Documentacion functions/{domain}/{name}.md — frontmatter YAML con metadata

Formato del .md (frontmatter YAML)

---
name: nombre_snake_case
kind: function                    # function | pipeline | component
lang: go                          # go | python | typescript | sql
domain: core                      # core | finance | datascience | cybersecurity | ...
version: "1.0.0"
purity: pure                      # pure | impure
signature: "func NombreCompleto(...) ..."
description: "Descripcion en español de que hace y cuando usarla."
tags: [tag1, tag2, tag3]
uses_functions: []                 # IDs de funciones del registry que invoca
uses_types: []                     # IDs de tipos del registry que recibe
returns: []                        # IDs de tipos del registry que devuelve
returns_optional: false
error_type: ""                     # ID de tipo de error, obligatorio si impure
imports: []                        # dependencias externas fuera del registry
tested: false
tests: []
test_file_path: ""
file_path: "functions/{domain}/{name}.go"
---

## Ejemplo

` `` go
resultado := MiFuncion(input)
` ``

## Notas

Explicacion adicional si es necesario.

Reglas de integridad (el indexer las valida)

Regla	Condicion
Pipeline siempre impuro	kind: pipeline -> purity: impure + uses_functions no vacio
Pura sin side effects	purity: pure -> returns_optional: false + error_type: ""
Impura declara errores	purity: impure -> error_type obligatorio (usar error_go_core)
Tests coherentes	tested: true -> test_file_path y tests obligatorios
Referencias validas	uses_functions, uses_types, returns, error_type deben apuntar a IDs existentes
Component tiene framework	kind: component -> framework obligatorio, returns vacio (usar emits)
Rutas relativas	file_path siempre relativa a la raiz, nunca absoluta
IDs unicos	Formato {name}_{lang}_{domain}, colisiones rechazadas

Campo returns vs tipo nativo

El campo returns en el .md es para IDs de tipos del registry (ej: ohlcv_go_finance), NO para tipos nativos de Go (float64, string, bool). Si la funcion devuelve tipos nativos, deja returns: [].

Despues de crear

# Regenerar el indice
./fn index
# o
CGO_ENABLED=1 go build -tags fts5 -o fn ./cmd/fn/ && ./fn index

# Verificar que se indexo sin errores
./fn show {name}_{lang}_{domain}

Reglas para añadir tipos nuevos

Cada tipo requiere dos archivos: types/{domain}/{name}.go y types/{domain}/{name}.md.

---
name: nombre_snake_case
lang: go
domain: core
version: "1.0.0"
algebraic: product                 # product (struct) | sum (interface/union)
definition: |
  type MiTipo struct { ... }
description: "Descripcion en español."
tags: [tag1, tag2]
uses_types: []                     # IDs de otros tipos que compone (sin auto-referencias)
file_path: "types/{domain}/{name}.go"
---

Convenciones

• IDs: {name}_{lang}_{domain} (ej: filter_slice_go_core)
• Nombres: snake_case para funciones, PascalCase para tipos en Go
• Paquete Go: el nombre del directorio (core, finance, datascience, cybersecurity)
• Tipos en firmas: usar tipos nativos (float64, []float64, string) para evitar imports circulares entre paquetes de funciones. Documentar los tipos del registry en uses_types/returns del .md
• Purity: puras en el centro, impuras en los bordes. Una pura NUNCA depende de una impura
• Stubs impuros: si la implementacion real requiere dependencias externas no disponibles, crear stub con return ..., fmt.Errorf("not implemented") y documentar completamente el .md

Fuentes de verdad

Que	Donde
Codigo	archivos .go / .py / .tsx
Documentacion	archivos .md junto al codigo
Diseño del schema	carpeta docs/
Indice de busqueda	registry.db (regenerable con fn index)

CLI (cmd/fn)

fn index                                   # Regenera registry.db desde los .md
fn search "texto"                          # Busqueda FTS
fn search -k function -p pure -d core "slice"
fn list                                    # Lista todo
fn list -d finance -k function             # Lista por dominio y kind
fn show filter_slice_go_core               # Muestra entrada completa
fn add -k function                         # Muestra template para copiar