graph_explorer/node_groups.h

#pragma once
#include <cstdint>
#include <string>
#include <unordered_map>
#include <vector>

// NodeGroups — vista tabular respaldada por DuckDB (issue 0010, renombrada
// en 0036a). Cada nodo `Table` del grafo apunta via metadata a un archivo
// `.duckdb` y a una tabla dentro de el. Las filas viven en DuckDB; el grafo
// solo materializa las que se "promueven" a entidades (issue 0011).
//
// Convencion de paths: `metadata.duckdb_path` es relativo al directorio del
// proyecto (la raiz donde vive operations.db). El caller resuelve a path
// absoluto antes de pasar a estas funciones.

namespace ge {

struct NodeGroupsRow {
    std::string id;                       // valor del id_column en duckdb (key natural)
    std::vector<std::string> values;      // un valor por columna en `columns[]`
    std::string promoted_entity_id;       // "" si la fila no esta promovida; sino, ops.entities.id
};

// Crea o sobrescribe el nodo Table. Inserta una fila en operations.db con
// type_ref='Table' y metadata apuntando al duckdb_path/table_name. Genera
// un id propio. Devuelve false si SQLite falla o si los argumentos basicos
// estan vacios.
bool node_groups_create(const char* ops_db,
                       const char* name,
                       const char* duckdb_path,
                       const char* duck_table,
                       const char* row_type,
                       char* out_id, std::size_t out_id_n);

// Cuenta las filas de duckdb_path/duck_table aplicando opcionalmente
// `sql_filter` (clausula WHERE sin la palabra WHERE — vacio = sin filtro).
// Devuelve false en error de IO/parse.
bool node_groups_count(const char* duckdb_path,
                      const char* duck_table,
                      const char* sql_filter,
                      int64_t* out);

// Devuelve una pagina ordenada por `id_column` ASC. Cada fila incluye los
// valores de `columns` resueltos a string + el flag `promoted_entity_id`
// computado via LEFT JOIN contra ops.entities (DuckDB attach a SQLite).
// limit clampeado en [1,5000].
bool node_groups_page(const char* duckdb_path,
                     const char* duck_table,
                     const char* id_column,
                     const std::vector<std::string>& columns,
                     const char* sql_filter,
                     const char* ops_db,           // para LEFT JOIN de promovidas
                     const char* row_type,         // discriminante en ops.entities
                     int64_t offset, int64_t limit,
                     std::vector<NodeGroupsRow>* out);

// Smoke test: abre el .duckdb, corre `SELECT 42 AS x` y verifica que
// devuelve la fila esperada. Devuelve true si todo OK.
bool node_groups_smoke_test(const char* duckdb_path);

// Resuelve un path posiblemente relativo a la ubicacion de operations.db.
// Si es absoluto (empieza por '/' o '<letra>:' en Windows), se devuelve
// tal cual.
std::string node_groups_resolve_path(const char* ops_db, const char* maybe_rel);

// Refresca el cache de conteos de filas por nodo Table. Lee
// type_ref='Table' de operations.db, extrae metadata.duckdb_path/table_name,
// llama a node_groups_count y guarda el resultado indexado por
// fnv1a64(entity_id) — la misma key que usa graph_sources al setear
// node.user_data, asi que el render puede mirar directo por user_data.
// Si una tabla falla, su entrada NO se inserta y se imprime un warning.
struct TableCounts {
    // user_data hash (fnv1a64 del entity id) -> total filas tras filter_sql.
    // -1 indica error/ausencia.
};
bool node_groups_refresh_counts(const char* ops_db,
                               std::unordered_map<uint64_t, int64_t>* out);

// ----------------------------------------------------------------------------
// Issue 0011 — UI fase 2 helpers
// ----------------------------------------------------------------------------

// Snapshot de la metadata relevante de un nodo Table. Caller-owned strings.
struct NodeGroupsMeta {
    std::string entity_id;
    std::string name;
    std::string duckdb_path;       // tal como aparece en metadata (relativo o absoluto)
    std::string duckdb_path_abs;   // resuelto con node_groups_resolve_path
    std::string table_name;
    std::string row_type;
    std::string id_column;
    std::string label_column;
    std::vector<std::string> columns;
    std::string filter_sql;
    bool        expanded = false;
};

// Lee la metadata del nodo Table (entidad type_ref='Table' con id=`entity_id`).
// Devuelve false si no existe o falla el JSON. Aplica defaults razonables a
// los campos faltantes (id_column='id', label_column='name').
bool node_groups_get_metadata(const char* ops_db, const char* entity_id,
                             NodeGroupsMeta* out);

// Persiste el flag `expanded` en la metadata. Idempotente. Devuelve false
// en error de IO/SQL.
bool node_groups_set_expanded(const char* ops_db, const char* entity_id,
                             bool expanded);

// Sobrescribe el array `columns` en la metadata. Llamar tras editar columnas
// desde la UI o tras node_groups_create cuando se descubren columnas.
bool node_groups_set_columns(const char* ops_db, const char* entity_id,
                            const std::vector<std::string>& columns);

// Promueve una fila de DuckDB a entidad del grafo. Idempotente: si ya existe
// una entidad con metadata.source.row_id == row_id Y metadata.source.duckdb
// == duckdb_path, devuelve esa misma id en out_id sin tocar nada.
//
// Si no existe, lee la fila de DuckDB con SELECT *, construye un id estable
// "prom_<sanitize(row_type)>_<sanitize(row_id)>", e inserta en ops.entities
// con type_ref=row_type, name = valor del label_column (o row_id si vacio),
// metadata = { source: {duckdb, table, row_id}, <columnas> }.
//
// Si table_entity_id no es nulo/vacio, inserta tambien una relacion
// CONTAINS_ROW (idempotente) entre la tabla y la nueva entidad para que el
// viewport pinte la arista de pertenencia.
bool node_groups_promote_row(const char* ops_db,
                            const char* table_entity_id,
                            const char* duckdb_path,
                            const char* duck_table,
                            const char* row_id,
                            const char* row_type,
                            const char* label_column,
                            char* out_entity_id, std::size_t out_id_n);

// Borra la entidad. La fila DuckDB sigue intacta. Devuelve true si la fila
// no existia (no-op idempotente).
bool node_groups_demote_row(const char* ops_db, const char* entity_id);

// Tipos de fichero soportados por node_groups_ingest_file.
enum IngestKind {
    INGEST_AUTO    = 0,  // detecta por extension
    INGEST_CSV     = 1,
    INGEST_PARQUET = 2,
    INGEST_JSON    = 3,
};

// Importa un fichero CSV/Parquet/JSON al `.duckdb`. Crea el .duckdb si no
// existe. Si la tabla destino existe, falla (no sobrescribe — explicit fail).
// Por defecto INGEST_AUTO inspecciona la extension del path.
bool node_groups_ingest_file(const char* duckdb_path,
                            const char* file_path,
                            const char* dest_table,
                            IngestKind  kind,
                            std::string* out_error);

// Lista los nombres de columna de la tabla DuckDB. Para popular la lista
// `columns` por defecto en node_groups_create.
bool node_groups_list_columns(const char* duckdb_path,
                             const char* duck_table,
                             std::vector<std::string>* out);

// ----------------------------------------------------------------------------
// Issue 0036b — kind discriminator + Group loader
// ----------------------------------------------------------------------------

// Loaders especificos para kind=Group. Operan sobre operations.db
// consultando `entities` filtrando por `group_id`. Las columnas del
// result son fijas (id, name, type_ref, status, updated_at) y se mapean
// a NodeGroupsRow.values en ese orden. Devuelven false si la query falla.
bool node_groups_count_for_group(const char* ops_db,
                                  const char* container_id,
                                  int64_t* out_total);

bool node_groups_page_for_group(const char* ops_db,
                                 const char* container_id,
                                 int64_t offset, int64_t limit,
                                 std::vector<NodeGroupsRow>* out_rows);

} // namespace ge