dataforge/fn_registry
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

close issue 0081: tables promoted to registry + fn doctor cpp-apps BeginTable check

Browse Source 
- docs/TQL.md: añadidas secciones joins, views, main_source, 24 viz tokens completos
  (extraidos de tql_helpers.cpp), color_rules, fn.* builtins completos (20 funciones),
  funciones bloqueadas del sandbox, tabla de estado de implementacion actualizada.
  Nota al pie referencia los 129 checks roundtrip (41 emit + 88 apply).

- functions/infra/audit_cpp_apps.go: añadida AuditCppTableMigration() que escanea
  .cpp de cada app imgui buscando ImGui::BeginTable; status CANDIDATE/MIXED/clean
  segun si usa data_table_cpp_viz en uses_functions.

- cmd/fn/doctor.go: fn doctor cpp-apps ahora incluye seccion BeginTable migration
  con tabwriter CANDIDATE/MIXED; --json produce {conformance, table_migration}.
  doctorAll incluye cpp_table_migration en el mapa JSON.

- .claude/rules/fn_doctor.md: tabla de subcomandos y acciones complementarias
  actualizadas con el nuevo check.

- dev/issues/0081 movido a completed/ con status done y notas de deuda documentadas.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Egutierrez
2026-05-15 14:49:56 +02:00
parent fad7b2fccc
commit acecbbc821
5 changed files with 470 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/TQL.md
+289 -20
View File
@@ -58,7 +58,7 @@ Independiente de los datos. La misma query puede renderizarse de N formas con un
### Implicaciones para TQL
TQL adopta esa separacion: `stages` (data) + `display` + `columns` (viz). Mismo patron, sintaxis Lua.
TQL adopta esa separacion: `stages` (data) + `display` + `columns` (viz) + `views` (paneles adicionales). Mismo patron, sintaxis Lua.
Cuando un boton futuro "Add visualization" se construya, anade un nuevo `display` + viz settings a una query existente sin tocar `stages`. Asi tendremos M visualizaciones (table, bar, line, scatter) sobre los mismos datos transformados.
@@ -103,6 +103,10 @@ input_cells (raw dataset)
return {
version = 1,
display = "table",
main_source = "functions", -- opcional: nombre de la fuente principal
-- JOINS: unir tablas adicionales antes de stage 0
joins = { ... }, -- opcional
-- DATA: pipeline de transformacion
stages = {
@@ -129,9 +133,14 @@ return {
color_rules = { {equals = "0.0", color = "#e08060"} }},
{name = "internal", type = "string", visible = false, order = 3},
},
visualization_settings = {
-- Futuro: opciones especificas del display (chart axes, paleta, stack, etc.)
-- VIEWS: paneles de visualizacion (index 1 = principal, resto = extras)
views = {
{display = "table"},
{display = "bar", x_col = "lang", y_cols = {"count"}},
},
visualization_settings = {},
}
```
@@ -139,6 +148,57 @@ return {
---
## `main_source`
Campo de cadena opcional. Identifica el nombre de la tabla/fuente principal del dataset. Usado por `tql_to_sql` para generar el `FROM "main_source"` correcto en el SQL emitido. Si esta vacio, el motor usa la tabla por defecto del contexto.
```lua
main_source = "functions"
```
En el SQL emitido: `FROM "functions"`. Util cuando la app expone multiples tablas y el agente necesita especificar explicitamente cual es la base del query.
---
## `joins`
Lista de joins que se aplican antes de stage 0. Los campos de las tablas unidas se añaden como columnas adicionales accesibles en todos los stages.
```lua
joins = {
{
alias = "t", -- prefijo para sus columnas ("t.field")
source = "types", -- nombre de la tabla a unir
strategy = "left", -- "left" | "inner" | "right" | "full"
on = {{"id", "t.id"}}, -- pares {col_izq, col_der}
fields = {"t.algebraic", "t.description"}, -- cols a incluir (opcional)
},
{
alias = "u",
source = "unit_tests",
strategy = "inner",
on = {{"id", "u.function_id"}, {"lang", "u.lang"}}, -- multi-key
},
}
```
**Estrategias:**
| Token | Semantica SQL |
|---|---|
| `"left"` | `LEFT OUTER JOIN` — todas las filas de la izq, nulls donde no hay match |
| `"inner"` | `INNER JOIN` — solo filas con match en ambas tablas |
| `"right"` | `RIGHT OUTER JOIN` — todas las filas de la der |
| `"full"` | `FULL OUTER JOIN` — todas las filas de ambas tablas |
Default si `strategy` se omite: `"left"`.
**Campos tras el join:** accesibles como `"alias.field"` (ej. `"t.algebraic"`) en filters, breakouts, aggregations y expressions. Si `fields` se omite, se incluyen todas las columnas de la tabla unida con prefijo alias.
**Join multi-key:** `on` es lista de pares; se traduce a `ON l.k1 = r.k1 AND l.k2 = r.k2`.
---
## `filter`
Lista de predicados. Multiples filters se combinan con AND implicito.
@@ -191,6 +251,15 @@ breakout = { "lang", "domain" }
Cada combinacion unica de valores `(lang, domain)` produce una fila en el output. Si `breakout` esta vacio pero hay `aggregation`, todo el dataset se reduce a UNA sola fila.
**Breakout con granularidad de fecha** — sufijo `:granularity` en el nombre de la col:
```lua
breakout = { "created_at:month", "lang" }
-- equivale a GROUP BY date_trunc('month', created_at), lang
```
Granularidades disponibles: `year`, `month`, `week`, `day`, `hour`.
**Disponible solo en stages >= 1.**
---
@@ -274,13 +343,97 @@ columns = {
**Cols que no aparecen en `columns`**: mantienen su estado UI actual (visible, posicion natural).
### `color_rules`
Reglas de color condicional por valor exacto. Se aplican al renderizar cada celda de la columna: si el valor de la celda es igual a `equals`, la celda se colorea con `color`.
```lua
color_rules = {
{equals = "go", color = "#86b56b"}, -- verde para Go
{equals = "py", color = "#6b8eb5"}, -- azul para Python
{equals = "bash", color = "#b58f6b"}, -- naranja para Bash
}
```
- Solo soporta igualdad exacta (string match). Para rangos numericos, usa una expression que produzca una etiqueta ("high"/"low") y aplica color_rules sobre esa columna derivada.
- Multiples reglas se evaluan en orden; la primera que hace match gana.
- Si ningun match: color por defecto del tema.
---
## `display`
Tipo de visualizacion. v1 solo `"table"`. Futuro: `"bar"`, `"line"`, `"scatter"`, `"pie"`, `"scalar"`, `"area"`, `"pivot"`. Default: `"table"`.
Tipo de visualizacion del panel principal. Default: `"table"`.
**Tokens validos (extraidos de `tql_helpers.cpp`):**
| Token | Tipo de chart |
|---|---|
| `"table"` | Tabla de datos (default) |
| `"bar"` | Barras horizontales |
| `"column"` | Barras verticales |
| `"grouped_bar"` | Barras agrupadas por categoria |
| `"stacked_bar"` | Barras apiladas |
| `"line"` | Lineas |
| `"area"` | Area rellena |
| `"stairs"` | Escalera (step function) |
| `"scatter"` | Dispersion XY |
| `"bubble"` | Dispersion XY con tamano variable |
| `"histogram"` | Histograma 1D |
| `"hist2d"` | Histograma 2D |
| `"heatmap"` | Mapa de calor |
| `"boxplot"` | Caja y bigotes |
| `"stem"` | Stem plot |
| `"errorbars"` | Barras de error |
| `"pie"` | Sectores (pie chart) |
| `"donut"` | Donut |
| `"funnel"` | Embudo |
| `"waterfall"` | Cascada |
| `"kpi"` | Metrica KPI (numero grande) |
| `"kpi_grid"` | Grid de KPIs |
| `"candlestick"` | Velas (OHLC) |
| `"radar"` | Radar / spider |
Token invalido: `tql_apply` genera warning `"unknown display"` y cae a `"table"`.
---
## `views`
Array de paneles de visualizacion. El indice 1 es el panel principal (equivale al `display` + `viz_config` del State); el resto son paneles extra que se muestran junto a la tabla.
```lua
views = {
-- Panel 0 (principal)
{display = "bar", x_col = "lang", y_cols = {"count"}, color = "#86b56b"},
-- Panel 1 (extra)
{display = "pie", cat_col = "lang", y_cols = {"sum_size_kb"}, show_legend = true},
}
```
**Campos por panel:**
| Campo | Tipo | Para que |
|---|---|---|
| `display` | string | Token de tipo de chart (ver tabla `display`) |
| `x_col` | string | Columna para eje X (bar, column, line, area, scatter, bubble, etc.) |
| `y_cols` | `{string,...}` | Columnas para eje Y. Multiple = multiple series |
| `cat_col` | string | Columna de categorias (pie, donut, funnel, radar) |
| `size_col` | string | Columna para tamano del burbuja (bubble) |
| `color` | string | Color primario `"#rrggbb"`. Sirve para series unicas o acento |
| `hist_bins` | int | Numero de bins para histogram / hist2d |
| `pie_radius` | float | Radio del donut interior (donut, 0.0 = pie solido) |
| `show_legend` | bool | Mostrar leyenda. Default `true` |
| `show_markers` | bool | Puntos en lineas/area. Default `false` |
| `locked` | bool | Panel fijo — el usuario no puede cerrarlo ni cambiar tipo |
Si `views` se omite, el emit lo serializa con un panel minimo que replica `state.display`.
---
## `visualization_settings`
Reservado para configuracion especifica por tipo de display. v1 vacio. Futuro:
Reservado para configuracion especifica por tipo de display. v1 siempre vacio (`{}`). Emitido por `tql_emit` para mantener el round-trip completo. Futuro:
```lua
visualization_settings = {
@@ -293,6 +446,8 @@ visualization_settings = {
Sintaxis Metabase: las keys con `.` van entre brackets `[]`.
---
## `sort`
Lista de clauses. Multi-sort por orden de aparicion (primera = primaria).
@@ -318,6 +473,8 @@ Pregunta: "Para las funciones puras con cobertura >= 80%, agrupa por lenguaje y
```lua
return {
version = 1,
display = "table",
stages = {
-- Stage 0: Raw + filter
{
@@ -350,6 +507,44 @@ return {
---
## Ejemplo con join + views
```lua
return {
version = 1,
display = "bar",
main_source = "functions",
joins = {
{
alias = "u",
source = "unit_tests",
strategy = "left",
on = {{"id", "u.function_id"}},
fields = {"u.name"},
},
},
stages = {
{ filter = {{"=", "lang", "go"}} },
{
breakout = {"domain"},
aggregation = {{"count"}, {"distinct", "id"}},
sort = {{"desc", "count"}},
},
},
columns = {
{name = "domain", type = "string", visible = true, order = 1},
{name = "count", type = "int", visible = true, order = 2},
},
views = {
{display = "bar", x_col = "domain", y_cols = {"count"}, show_legend = false},
{display = "donut", cat_col = "domain", y_cols = {"count"}, show_legend = true},
},
visualization_settings = {},
}
```
---
## Drill-down (semantica)
Si el usuario interactua con una celda agrupada del stage N, hace **drill-down**:
@@ -387,8 +582,7 @@ Las strings dentro de `expressions` siguen el mini-DSL Lua de columnas custom. R
- Type-aware: cell de col Int/Float llega como number; Bool como boolean; resto como string. Vacia = nil.
- UTF-8 ok en nombres `[año]`.
- Comentarios `--` y `--[[ ]]` respetados.
- Builtins disponibles via `fn.*`: `upper, lower, length, substring, contains, starts_with, ends_with, replace, trim, concat, to_number, to_string, to_bool, is_null, is_empty, coalesce, parse_date, year, month, day`.
- Sandbox: sin `io`, `require`, `dofile`, `loadfile`, `load`, `package`, `debug`. `os` recortado a `date/time/difftime/clock`.
- Nombres de cols con espacios y puntos soportados en brackets: `[col con espacio]`, `[alias.field]`.
Ejemplos:
@@ -397,21 +591,73 @@ Ejemplos:
fn.concat([lang], ":", [domain]) -- string compose
if [coverage_pct] >= 90 then "well" else "low" end
fn.year([updated_at]) -- date helper
fn.coalesce([error_type], "none") -- null handling
```
---
## Funciones Lua disponibles (`fn.*`)
El sandbox expone estas funciones via la tabla global `fn`. Registradas en `lua_engine.cpp::register_builtins`:
| Funcion | Firma | Que hace |
|---|---|---|
| `fn.upper(s)` | string -> string | Convierte a mayusculas (ASCII) |
| `fn.lower(s)` | string -> string | Convierte a minusculas (ASCII) |
| `fn.length(s)` | string -> int | Longitud en bytes (`strlen`); nil -> 0 |
| `fn.substring(s, start [, len])` | string, int[, int] -> string | Subcadena 1-based; len omitido = hasta el final |
| `fn.contains(haystack, needle)` | string, string -> bool | True si needle aparece en haystack |
| `fn.starts_with(s, prefix)` | string, string -> bool | True si s empieza por prefix |
| `fn.ends_with(s, suffix)` | string, string -> bool | True si s termina por suffix |
| `fn.replace(s, find, repl)` | string, string, string -> string | Reemplaza todas las ocurrencias de find por repl |
| `fn.trim(s)` | string -> string | Elimina espacios/tabs/newlines del inicio y fin |
| `fn.concat(...)` | vararg -> string | Concatena N argumentos como string |
| `fn.to_number(s)` | string -> number\|nil | Parsea a numero; nil si no parseable |
| `fn.to_string(x)` | any -> string | Convierte a string (usa `luaL_tolstring`) |
| `fn.to_bool(x)` | any -> bool | True si `"true"` o `"1"` |
| `fn.is_null(x)` | any -> bool | True si x es nil |
| `fn.is_empty(x)` | any -> bool | True si x es nil o string vacia |
| `fn.coalesce(...)` | vararg -> any | Devuelve el primer argumento no-nil |
| `fn.parse_date(s)` | string -> table\|nil | Parsea `"YYYY-MM-DD"` -> `{year, month, day}` |
| `fn.year(s)` | string -> int\|nil | Extrae el año de `"YYYY-..."` |
| `fn.month(s)` | string -> int\|nil | Extrae el mes de `"YYYY-MM-..."` |
| `fn.day(s)` | string -> int\|nil | Extrae el dia de `"YYYY-MM-DD"` |
Ademas, las librerias Lua estandar `string`, `table`, `math`, `os` (recortado) estan disponibles.
---
## Sandbox — funciones bloqueadas
El engine aplica el sandbox via `lua_engine.cpp::apply_sandbox`. Globals eliminados:
| Global | Por que bloqueado |
|---|---|
| `io` | I/O de archivos y stdin/stdout |
| `require` | Carga de modulos externos |
| `loadfile` | Ejecucion de archivos Lua arbitrarios |
| `dofile` | Idem |
| `load` | Compilacion y ejecucion de strings arbitrarias |
| `package` | Sistema de paquetes Lua |
| `debug` | Introspection de call stack / upvalues |
`os` se sustituye por una version recortada que solo expone: `os.date`, `os.time`, `os.difftime`, `os.clock`. El resto de `os` (ejecutar comandos, salir, setenv, etc.) se elimina.
Las formulas de expresiones se compilan con `luaL_loadbufferx(..., "t")` — el flag `"t"` rechaza bytecode precompilado (solo acepta texto source).
---
## Restricciones v1
| No soportado | Workaround |
|---|---|
| Joins entre tablas | Pre-procesar fuera del registry. |
| Subqueries SQL | Usar stages encadenados (modelo equivalente). |
| `HAVING` post-aggregation | Stage siguiente con `filter` sobre cols agregadas. |
| `LIMIT` | TBD — añadir como `limit = N` en stage v2. |
| Window functions | TBD. |
| Custom aggregation Lua | TBD — `{"lua", "col", "<body>"}`. |
| Alias custom en aggregation v1 | Crear expression post-grupo. |
| color_rules con rangos numericos | Usar expression que emita etiquetas; aplicar color_rules sobre la etiqueta. |
| Multiples fuentes sin join | Declarar cada fuente adicional en `joins`. |
---
@@ -423,11 +669,21 @@ Cuando expongas TQL a un LLM, dale este preambulo:
You output TQL — a Lua table that describes a table transformation. Format:
return {
version = 1,
display = "table", -- table|bar|column|grouped_bar|stacked_bar|line|area|stairs|scatter|
-- bubble|histogram|hist2d|heatmap|boxplot|stem|errorbars|
-- pie|donut|funnel|waterfall|kpi|kpi_grid|candlestick|radar
main_source = "...", -- optional: name of main table/source
joins = { ... }, -- optional: join additional tables
stages = {
{ filter = {...}, expressions = {...}, sort = {...} }, -- Stage 0 (Raw)
{ filter = {...}, breakout = {...}, aggregation = {...}, sort = {...} }, -- Stage 1+
...
}
},
views = {
{display="...", x_col="...", y_cols={...}, cat_col="...", color="...", ...}, -- panel 0 = main
... -- extra panels
},
}
Rules:
@@ -437,6 +693,9 @@ Rules:
Available fns: count, sum, avg, min, max, distinct, stddev, median, p25, p75, p90, p99, percentile.
- Sort: {{"desc", "col"}, ...}. Multi-sort por orden de la lista.
- Expressions value es una expresion Lua. Acceso a cols via [col_name].
- Joins: alias + source + strategy (left/inner/right/full) + on pairs + optional fields list.
- Views: array de paneles, index 1 = principal. display token from the list above.
- color_rules: [{equals="val", color="#rrggbb"}, ...] dentro de cada entry de columns.
The available columns of the current input table are: <inject runtime>.
The available column types: <inject runtime>.
@@ -483,19 +742,25 @@ StageOutput compute_stage(const char* const* in_cells, int in_rows, int in_cols,
| Feature | Status |
|---|---|
| `Stage` + `Aggregation` types | done |
| `compute_stage` (filter + group + agg + sort) | done (Phase 1) |
| `compute_stage` (filter + group + agg + sort) | done |
| Todas las aggregations (count..percentile) | done |
| `aggregation_alias` / `aggregation_type` | done |
| Multi-sort por stage | done |
| Tests E2E logica | done (37 checks) |
| `tql_emit` / `tql_apply` (Lua round-trip) | Phase 2 (pendiente) |
| State refactor a `vector<Stage>` | Phase 3 (pendiente) |
| UI breadcrumb stages + chips por stage | Phase 3 (pendiente) |
| Drill-down interactivo | Phase 3 (pendiente) |
| Show TQL / Apply TQL modals | Phase 2 |
| Multi-sort drag-reorder | Phase 4 |
Ver `cpp/apps/primitives_gallery/playground/tables/` para la implementacion del playground.
| Tests E2E logica | done (129 checks en tql_emit_test + tql_apply_test) |
| `tql_emit` / `tql_apply` (Lua round-trip) | done |
| `views` (paneles de visualizacion) | done |
| `main_source` | done |
| `joins` (left/inner/right/full, multi-key, fields) | done |
| `color_rules` por columna | done |
| `breakout` con granularidad de fecha | done |
| Lua sandbox (`fn.*` builtins, sin io/require/load) | done |
| 24 tipos de viz (table, bar, column, pie, donut...) | done |
| `tql_to_sql` (SQL DuckDB emit) | done (issue 0080) |
| State refactor a `vector<Stage>` | done |
| UI breadcrumb stages + chips por stage | done |
| Drill-down interactivo | done |
| Show TQL / Apply TQL modals | done |
| Multi-sort drag-reorder | done |
---
@@ -580,3 +845,7 @@ SQL transpile error en derived col 'fullname':
- **Agente flow:** TQL default. SQL solo si app linko DuckDB. UI Ask AI muestra toggle SQL solo cuando disponible.
Ver issue 0080 + `tql_to_sql.{h,cpp}` para implementacion.
---
*Generado a partir de los tests roundtrip en `cpp/functions/core/tql_emit_test.cpp` y `cpp/functions/core/tql_apply_test.cpp` — 129 checks (41 emit + 88 apply) en verde garantizan compatibilidad del round-trip State <-> Lua.*