nan-graph

In-memory Architecture Graph engine — la implementación del grafo de SOFE Architecture Graph (fusión Ñan × BYaML v2). OSS, Apache-2.0, bajo breakingthecloud.

Un grafo dirigido en memoria con relaciones tipadas, para análisis de arquitectura: traversal BFS/DFS, blast radius, cost chain, fan-in / SPOF, y filtrado por tipo de relación.

Cero infraestructura: funciona en Node.js, Cloudflare Workers, Lambda. Zero deps en el core (la importación YAML usa el paquete ligero yaml).

📚 Developer Docs

Documentación completa para desarrolladores en docs/: Getting Started · Concepts · API Reference · Contribution

Install

pnpm add @carloscortezcloud/nan-graph

Uso

import { NanGraph, blastRadius, costChain, fromYaml } from '@carloscortezcloud/nan-graph';

const g = new NanGraph()
  .addNode({ id: 'api', type: 'aws.apigateway', attrs: { monthly_cost: 20 } })
  .addNode({ id: 'lambda', type: 'aws.lambda', attrs: { monthly_cost: 5 } })
  .addNode({ id: 'ddb', type: 'aws.dynamodb', attrs: { monthly_cost: 30 } })
  .addEdge({ from: 'api', to: 'lambda', relType: 'routes_to' })
  .addEdge({ from: 'lambda', to: 'ddb', relType: 'reads_writes' });

blastRadius(g, 'api');   // ['lambda', 'ddb']  — qué se cae si api falla
costChain(g, 'api');     // 55 — costo downstream total

Importar desde YAML / JSON

import { fromYaml } from '@carloscortezcloud/nan-graph';

// estilo dependency-graph.yaml
const g = fromYaml(`
nodes:
  sofe-engine: { type: python-library }
  sofe-server: { type: python-api }
edges:
  - { from: sofe-engine, to: sofe-server, relType: bundles }
`);

// estilo BYaML v0.3 (components + relationships)
const g2 = fromObject({
  components: [{ id: 'api', type: 'aws.apigateway', monthly_cost: 20 }],
  relationships: [{ from: 'api', to: 'lambda', type: 'routes_to' }],
});

API

| Función | Descripción | |---------|-------------| | new NanGraph() | Grafo dirigido multi-borde en memoria | | g.addNode(node) / g.addEdge(edge) | Añadir nodo/arista (auto-crea nodos) | | g.getRelated(id, relType?, direction?) | Vecinos outgoing/incoming/both, con filtro | | traverseBFS(g, start, opts) | Nodos alcanzables (BFS), con relTypes/maxDepth/direction | | traverseDFS(g, start, opts) | Nodos alcanzables (DFS) | | blastRadius(g, start) | Nodos afectados downstream si start falla | | costChain(g, start) | Suma attrs.monthly_cost de start + downstream | | teamCost(g, owner) | Suma de costo por attrs.owner | | fanIn(g, id) / singlePointsOfFailure(g, threshold) | SPOF por alta dependencia entrante | | fromObject(obj) / fromYaml(str) / fromJson(str) | Construir grafo desde input |

Modelo (fusión con SOFE Architecture Graph)

• Nodo = unidad desplegable / recurso / servicio / documento (id, type, label, attrs).
• Arista = relación dirigida tipada (from, to, relType).
• Derivado de SOFE engine/architecture.py (blast_radius, cost_chain, fan_in, spof)
  • cc-mng graph/data.ts (GraphNode/GraphEdge) + dependency-graph.yaml como formato de input.

Sync a PyPI

El port en Python (nan-graph en PyPI) se sincroniza desde este core TS — mismo patrón que styrr → styrr-py. Ver SoW nan-001.

Licencia

Apache-2.0. Ver LICENSE.