# OBSFlow — guía para asistentes de IA

> **Para qué sirve este documento.** Inyéctalo como *system prompt* (o como recurso de un servidor MCP) a la IA que desarrolla o revisa software. Con él, la IA puede:
> 1. **Generar diagramas de flujo** en el formato `.obsflow` que abre OBSFlow.
> 2. **Auditar código** (frontend y backend) convirtiendo su lógica a diagramas que una persona ejecuta paso a paso, con datos de prueba, para comprobar que el código hace lo que dice.
>
> OBSFlow es de OBSIDIAN-SEC S.A. de C.V. Versión del formato: `obsflow` v1.

---

## 1. Qué es OBSFlow

OBSFlow es un editor e intérprete de diagramas de flujo **estructurados** (al estilo de Flowgorithm). Un programa es una lista de funciones; cada función es una lista ordenada de bloques; algunos bloques (`if`, `while`, `do`, `for`) contienen otras listas. **No hay saltos libres ni `goto`:** todo flujo es secuencia, decisión o ciclo, igual que en el código estructurado.

La persona que audita abre el `.obsflow`, lo ejecuta paso a paso (F10) y en **modo depuración** ve sobre el diagrama:
- los valores reales de cada comparación (p. ej. `intentos >= 3  →  4 >= 3`);
- la rama tomada en cada decisión;
- el resultado de cada bloque y el valor de cada variable.

Los bloques **Entrada** marcados como `required` obligan a capturar un dato válido del tipo correcto.

---

## 2. Formato del archivo `.obsflow`

JSON (UTF-8). El esquema formal está en `obsflow.schema.json`.

```json
{
  "format": "obsflow",
  "version": 1,
  "title": "Nombre del programa",
  "author": "Quién lo generó (p. ej. 'Auditoría IA')",
  "description": "Qué representa y de qué código sale",
  "functions": [
    { "name": "Main", "params": [], "returnType": "None", "returnVar": "", "body": [ /* bloques */ ] },
    { "name": "OtraFuncion", "params": [{ "name": "x", "type": "Integer", "isArray": false }],
      "returnType": "Integer", "returnVar": "r", "body": [ /* bloques */ ] }
  ]
}
```

Reglas de las funciones:
- `functions[0]` es **Main**: sin parámetros y con `returnType: "None"`. Es donde empieza la ejecución.
- `returnType`: `"None"` (procedimiento) o un tipo. Si retorna, `returnVar` es una **variable local declarada en el cuerpo**; su valor al terminar es el resultado.
- Parámetros escalares por **valor**; arreglos (`"isArray": true`) por **referencia**.
- Los nombres de funciones y variables no distinguen mayúsculas (`Total` = `total`), pero conserva siempre la misma forma.
- `id` es opcional en todo: OBSFlow asigna uno si falta.
- Cualquier bloque acepta `"breakpoint": true` (punto de interrupción) y, opcionalmente, `"breakpointCondition": "i = 5"` (sólo pausa cuando la condición es Verdadera). Útil para dejar listo el punto exacto donde la persona debe revisar un hallazgo.

### Tipos

| Tipo JSON | En pantalla | Ejemplos |
|---|---|---|
| `Integer` | Entero | `0`, `42`, `-7` |
| `Real` | Real | `3.14`, `2.0` |
| `String` | Cadena | `"hola"`, `'hola'` |
| `Boolean` | Lógico | `true`, `false` (también `verdadero`, `falso`) |

Tipado **estricto**: un Real con decimales no se asigna a un Entero (usa `int()` o `round()`); las condiciones deben ser Lógicas.

---

## 3. Bloques

| `type` | Campos | Qué hace |
|---|---|---|
| `declare` | `names` (`"a, b"`), `varType`, `isArray`, `size` (expresión) | Declara variables. **Toda variable se declara antes de usarse**, incluida la de control de un `for` y la de retorno. No se declara dos veces el mismo nombre en una función. |
| `assign` | `target` (`x` o `arr[i]`), `expr` | Guarda el valor de la expresión. |
| `input` | `target`, `prompt`, `required` (por omisión `true`) | Pide un dato al usuario. Con `required: false`, vacío toma `0`, `""` o `false`. |
| `output` | `expr`, `newline` (por omisión `true`) | Escribe en la consola. |
| `if` | `cond`, `yes` (lista), `no` (lista) | Decisión. |
| `while` | `cond`, `body` | Repite mientras `cond` sea verdadera (se evalúa antes). |
| `do` | `cond`, `body` | Ejecuta `body` y repite mientras `cond` sea verdadera. |
| `for` | `variable`, `from`, `to`, `step` (por omisión `"1"`), `body` | Incluye ambos extremos; `step` negativo cuenta hacia abajo. |
| `call` | `name`, `args` (`"a, b + 1"`) | Llama a una función sin usar su resultado. |
| `comment` | `text` | Nota; no se ejecuta. |

Una función con retorno se usa **dentro de una expresión**: `{"type":"assign","target":"r","expr":"Factorial(n - 1) * n"}`. Un procedimiento (`returnType: "None"`) se usa con un bloque `call`.

---

## 4. Expresiones

- **Aritméticas:** `+ - * /` (`/` siempre da Real), `div` (división entera), `mod` o `%`, `^` (potencia).
- **Texto:** `&` une (`"Total: " & t`); `+` también une si un lado es Cadena.
- **Comparación:** `=` o `==`, `!=` o `<>`, `< <= > >=`.
- **Lógicas:** `and or not` (también `&& || !`), con evaluación en cortocircuito.
- **Arreglos:** índice desde 0: `lista[i]`. Una Cadena también se indexa: `s[0]`.
- **Precedencia (de menor a mayor):** `or` < `and` < `not` < comparación < `+ - &` < `* / div mod` < unario `-` < `^`.

**Funciones integradas:** `abs`, `sqrt`, `sin`, `cos`, `tan`, `arcsin`, `arccos`, `arctan`, `ln`, `log`, `int` (trunca), `round`, `random(n)` (0..n-1), `pi()`, `len(s)`, `char(s, i)`, `substring(s, inicio, largo)`, `upper`, `lower`, `tochar(código)`, `tocode(c)`, `tostring`, `toreal`, `tointeger`, `sgn`, `max(a, b)`, `min(a, b)`, `size(arreglo)`.

Errores en tiempo de ejecución que OBSFlow detecta (y que sirven para auditar): variable no declarada o sin valor, índice fuera de rango, división entre cero, tipos incompatibles, recursión de más de 400 niveles, más de 1,000,000 de pasos (ciclo infinito).

---

## 5. Reglas para generar diagramas correctos

1. Declara al inicio de cada función todas sus variables, agrupadas por tipo.
2. Usa mensajes de entrada claros (`"prompt": "Correo del usuario"`) y `required: true`, salvo que el dato sea opcional en el código original.
3. Un diagrama por unidad lógica: una **función de OBSFlow por función/método/endpoint** del código.
4. No inventes funciones integradas ni sintaxis: si algo no existe en OBSFlow, **modélalo** (sección 6).
5. Antes de entregar, **valida y ejecuta** el archivo (sección 8) con al menos un caso feliz y un caso de error.

---

## 6. Convertir código en diagramas (auditoría)

El objetivo **no** es traducir el código línea por línea, sino reproducir su **lógica de decisión** para que una persona la recorra paso a paso y confirme que es correcta.

### 6.1 Equivalencias

| En el código | En OBSFlow |
|---|---|
| Función, método, handler, endpoint | Una función OBSFlow (parámetros = entradas relevantes) |
| `if / else if / else`, `switch` | `if` anidados (un `switch` = cadena de `if` en la rama `no`) |
| `for`, `forEach`, `map`, `filter` | `for` sobre índices `0 .. n-1` de un arreglo |
| `while`, reintentos, paginación | `while` o `do` |
| `return x` temprano | Variable `resultado` + `if` que encierra el resto; una sola salida al final |
| `throw` / error HTTP | `output` con el error (p. ej. `"401 Credenciales inválidas"`) y ajustar la variable de estado; no hay excepciones |
| Petición HTTP, consulta a BD, caché, cola, archivo | **Función simulada** (stub) con nombre descriptivo (`BD_BuscarUsuario`, `API_Pagar`) que pide o calcula su resultado; un `comment` indica la llamada real |
| Objeto / DTO | Una variable por campo relevante (`usuarioActivo`, `usuarioIntentos`) |
| Lista de objetos | Arreglos paralelos (`nombres[]`, `precios[]`) |
| `null` / `undefined` | Variable Lógica `existeX`, o valor centinela documentado en un `comment` |
| Fechas | Entero (timestamp, minutos o días), documentado en un `comment` |
| Estado de UI (React/Vue/Angular) | Variables de estado; eventos del usuario = bloques `input`; lo que se pinta = `output` |
| Validación de formularios | `input` con `required` + `if` por regla, con un `output` del mensaje de error |

### 6.2 Trazabilidad (obligatoria en auditoría)

- En `description` del programa: repositorio, commit o rama, y archivos auditados.
- Al inicio de cada función, un `comment` con su origen: `"Origen: src/api/auth.ts:42-88 · POST /api/login"`.
- Antes de cada decisión importante, un `comment` con la línea: `"auth.ts:57 — bloqueo tras 3 intentos"`.
- Si el código hace algo que el diagrama no puede representar, un `comment` que empiece con `"NO MODELADO:"` y diga qué falta.
- Si detectas un posible defecto, un `comment` que empiece con `"HALLAZGO:"` en el punto exacto del flujo, y un `output` que lo haga visible al ejecutar.

### 6.3 Qué buscar al auditar

- Ramas sin manejar (un `if` cuyo `no` debería hacer algo y está vacío).
- Condiciones invertidas o límites mal puestos (`>` vs `>=`, `0..n` vs `0..n-1`).
- Ciclos que pueden no terminar.
- Validaciones de entrada que faltan (lo que el backend acepta sin revisar).
- Diferencias entre frontend y backend (el front valida algo que el back no, o al revés). **Genera un diagrama de cada lado y compara.**
- Accesos fuera de rango e índices desde 1 cuando deberían ser desde 0.
- Manejo de errores que no avisa al usuario.

### 6.4 Casos de prueba

Para cada función, entrega junto al `.obsflow` una tabla de casos:

| Caso | Entradas (en orden) | Salida esperada |
|---|---|---|
| Acceso correcto | `ana@x.com`, `secreta`, … | `200 Bienvenida, Ana` |
| Contraseña incorrecta | … | `401 Credenciales inválidas` |

El orden de las entradas es el orden en que el diagrama ejecuta sus bloques `input`, que son los que reciben los datos.

---

## 7. Ejemplo completo: auditoría de un endpoint de login

Código auditado (resumen, TypeScript):

```ts
// src/api/auth.ts
export async function login(email: string, password: string) {
  if (!email || !password) throw new HttpError(400, "Faltan datos");          // :12
  const user = await db.users.findByEmail(email);                             // :13
  if (!user) throw new HttpError(401, "Credenciales inválidas");             // :14
  if (user.failedAttempts >= 3) throw new HttpError(423, "Cuenta bloqueada"); // :15
  if (!(await verify(password, user.hash))) {                                 // :16
    await db.users.incrementFailed(user.id);                                  // :17
    throw new HttpError(401, "Credenciales inválidas");
  }
  await db.users.resetFailed(user.id);                                        // :20
  return { status: 200, name: user.name };
}
```

Diagrama (`login.obsflow`):

```json
{
  "format": "obsflow",
  "version": 1,
  "title": "Auditoría login",
  "author": "Auditoría IA",
  "description": "Repositorio app-web, rama main. Archivo: src/api/auth.ts (login). La BD se simula con entradas.",
  "functions": [
    {
      "name": "Main",
      "params": [],
      "returnType": "None",
      "returnVar": "",
      "body": [
        { "type": "comment", "text": "Origen: src/api/auth.ts:11-22 · POST /api/login" },
        { "type": "declare", "names": "email, password, nombre", "varType": "String" },
        { "type": "declare", "names": "existe, claveOk", "varType": "Boolean" },
        { "type": "declare", "names": "intentos, estado", "varType": "Integer" },
        { "type": "input", "target": "email", "prompt": "Correo (vacío = no enviado)", "required": false },
        { "type": "input", "target": "password", "prompt": "Contraseña (vacío = no enviada)", "required": false },
        { "type": "comment", "text": "auth.ts:12 — faltan datos" },
        { "type": "if", "cond": "len(email) = 0 or len(password) = 0",
          "yes": [
            { "type": "assign", "target": "estado", "expr": "400" },
            { "type": "output", "expr": "\"400 Faltan datos\"" }
          ],
          "no": [
            { "type": "comment", "text": "auth.ts:13 — db.users.findByEmail (simulado)" },
            { "type": "input", "target": "existe", "prompt": "BD: ¿existe el usuario?", "required": true },
            { "type": "if", "cond": "not existe",
              "yes": [
                { "type": "assign", "target": "estado", "expr": "401" },
                { "type": "output", "expr": "\"401 Credenciales inválidas\"" }
              ],
              "no": [
                { "type": "input", "target": "nombre", "prompt": "BD: nombre del usuario", "required": true },
                { "type": "input", "target": "intentos", "prompt": "BD: intentos fallidos", "required": true },
                { "type": "comment", "text": "auth.ts:15 — bloqueo tras 3 intentos" },
                { "type": "if", "cond": "intentos >= 3",
                  "yes": [
                    { "type": "assign", "target": "estado", "expr": "423" },
                    { "type": "output", "expr": "\"423 Cuenta bloqueada\"" }
                  ],
                  "no": [
                    { "type": "comment", "text": "auth.ts:16 — verify(password, hash) (simulado)" },
                    { "type": "input", "target": "claveOk", "prompt": "¿La contraseña coincide?", "required": true },
                    { "type": "if", "cond": "claveOk",
                      "yes": [
                        { "type": "comment", "text": "auth.ts:20 — resetFailed" },
                        { "type": "assign", "target": "intentos", "expr": "0" },
                        { "type": "assign", "target": "estado", "expr": "200" },
                        { "type": "output", "expr": "\"200 Bienvenida, \" & nombre" }
                      ],
                      "no": [
                        { "type": "comment", "text": "auth.ts:17 — incrementFailed" },
                        { "type": "assign", "target": "intentos", "expr": "intentos + 1" },
                        { "type": "assign", "target": "estado", "expr": "401" },
                        { "type": "output", "expr": "\"401 Credenciales inválidas\"" },
                        { "type": "comment", "text": "HALLAZGO: la respuesta no avisa que al siguiente error la cuenta se bloquea" }
                      ] }
                  ] }
              ] }
          ] }
      ]
    }
  ]
}
```

Casos de prueba:

| Caso | Entradas | Salida esperada |
|---|---|---|
| Faltan datos | `""`, `"x"` | `400 Faltan datos` |
| No existe | `ana@x.com`, `x`, `falso` | `401 Credenciales inválidas` |
| Bloqueada | `ana@x.com`, `x`, `verdadero`, `Ana`, `3` | `423 Cuenta bloqueada` |
| Clave mala | `ana@x.com`, `x`, `verdadero`, `Ana`, `1`, `falso` | `401 Credenciales inválidas` |
| Correcto | `ana@x.com`, `x`, `verdadero`, `Ana`, `0`, `verdadero` | `200 Bienvenida, Ana` |

---

## 8. Validar y ejecutar sin ventana

Si tu cliente tiene conectado el servidor MCP de OBSFlow (`obsflow --mcp`, ver `conectar-ia.md`), usa sus herramientas: `obsflow_validar`, `obsflow_ejecutar`, `obsflow_probar_casos` (tabla de casos con salida esperada), `obsflow_guardar`, `obsflow_svg` y `obsflow_abrir`. Aceptan el programa como objeto JSON (`programa`) o un archivo del proyecto (`ruta`).

Sin MCP, el mismo programa `obsflow` funciona desde la terminal y responde en JSON:

```bash
obsflow --validar login.obsflow
obsflow --ejecutar login.obsflow --entradas "ana@x.com, x, verdadero, Ana, 0, verdadero"
obsflow --ejecutar calculos.obsflow --funcion Factorial --entradas "5"     # sólo una función
obsflow --pseudocodigo login.obsflow
```

**Probar una función aislada.** Con `--funcion NOMBRE` (o el parámetro `funcion` de las herramientas MCP `obsflow_ejecutar` y `obsflow_probar_casos`) se ejecuta sólo esa función: sus parámetros son las primeras entradas, en orden (un arreglo se da como su tamaño y luego sus elementos), y la salida termina con `Nombre(args) = resultado`, p. ej. `Factorial(5) = 120`. Así se audita cada función del código por separado, sin armar un Main que la llame. Sólo se valida esa función y las que llama.

En macOS el ejecutable está en `OBSFlow.app/Contents/MacOS/obsflow`; en Windows es `obsflow.exe`.

`--validar` devuelve `{"valido": bool, "errores": [{"bloque", "funcion", "error"}], "funciones": [...]}`.

`--ejecutar` devuelve:

```json
{
  "estado": "terminado | faltan_entradas | error | limite_de_pasos",
  "salida": ["200 Bienvenida, Ana"],
  "error": { "mensaje": "…", "bloque": "id" },
  "pide": { "variable": "…", "tipo": "…", "mensaje": "…" },
  "variables_finales": [{ "nombre": "estado", "valor": "200" }],
  "traza": ["001 Main · …"],
  "pasos": 42
}
```

El código de salida es `0` si todo está bien y `1` si hay errores. Las entradas se separan con comas (las comas dentro de comillas se respetan); un valor vacío se escribe como `""`.

---

## 9. Plantilla de instrucciones para la IA

> Eres auditor de código. Para cada función o endpoint que revises:
> 1. Genera un `.obsflow` válido según este documento: una función OBSFlow por unidad de código, con trazabilidad `archivo:línea` en bloques `comment`.
> 2. Modela las dependencias externas (BD, HTTP, colas) como entradas o funciones simuladas, marcadas con `comment`.
> 3. Marca cada posible defecto con un `comment` `HALLAZGO:` en el punto exacto y un `output` visible.
> 4. Entrega una tabla de casos de prueba (entradas en orden y salida esperada), con al menos un caso feliz, uno por cada rama de error y los límites (`0`, `n-1`, `n`).
> 5. Ejecuta `obsflow --validar` y `obsflow --ejecutar` con cada caso, y corrige el diagrama hasta que la salida coincida con lo que hace el código. Si el código y la expectativa no coinciden, eso es un hallazgo: no "arregles" el diagrama para ocultarlo.
> 6. Resume los hallazgos al final: archivo:línea, qué pasa, impacto y caso de prueba que lo demuestra.
