bib-graphify Fase 7: Cobertura TypeScript del grafo de conocimiento

Resumen

La Fase 7 de bib-graphify (tareas F7.4 + F7.5) cierra el gap estructural del grafo de conocimiento de la Biblioteca/Supercontexto: antes del commit b831fb5, el grafo solo indexaba código Python (~3.170 nodos); tras esta fase incorpora también todo el TypeScript/TSX del workspace, añadiendo +669 nodos y 718 edges en el backfill inicial.

Autor: @Esquembri · Fecha: 2026-04-24 · Commit: b831fb5

Motivación

El grafo de conocimiento es la base del Supercontexto: permite a los agentes IA encontrar cualquier función, componente o servicio por nombre. Sin cobertura TypeScript, el 100% del frontend (Astro + React) y los handlers de Cloudflare Workers quedaban fuera del grafo — los agentes no podían responder preguntas como “¿dónde está HealthWidget?” o “¿qué hace checkWiki?”.

El gap era conocido desde la Fase 5 (solo Python, ~3.170 nodos). La Fase 7 lo cierra sin añadir nuevas dependencias ni cambiar la arquitectura del grafo.

Tareas

F7.4 — Diseño e implementación del extractor TS

Diseño de bib_ast_ts.mjs:

Parser: TypeScript Compiler API nativa (typescript@^6.0.2, ya presente).
Prefix qualified_name: ts:<path>::<name> — sin colisión con Python dot-path.
node_types: js_module, function, class, method, schema (reusa los existentes del grafo D1).
Metadatos de componentes React: is_component=true + returns_jsx=true detectados automáticamente.
Campo app: mapeado desde el primer segmento del path (functions-mcp, functions-api, components, lib, pages…).
Edges v1: contains, imports, inherits, calls (resolución local únicamente).
CLI: compatible con el patrón de bib_ast.py (--stats, --output, --push, --roots).

F7.5 — Backfill inicial

Ejecución del extractor sobre el workspace completo el 2026-04-24:

Run 4278:
  nodes_created : 669
  nodes_updated : 0
  edges_created : 718
  errors        : 0
  duration      : 2.221s

Impacto en el grafo

Antes (solo Python)

Tipo	Nodos
endpoints	495
function	986
model	95
class	308
schema	198
Total	~3.170

Después (Python + TypeScript)

Tipo	Nodos	Delta
js_module	136	+136
function	1.328	+342
schema	389	+191
endpoints	495	—
model	95	—
class	308	—
Total	3.839	+669

Los dominios Python permanecen intactos (495 endpoints, 95 models, 308 classes).

Validación de cierre del gap

# Antes: 0 hits / Después: resultados
bib_search_nodes('checkWiki')        → 1 hit
bib_search_nodes('HealthWidget')     → 5 hits
bib_search_nodes('fetchBiblioteca*') → 1 hit

Alcance de indexación

Roots por defecto: functions/, src/
Extensiones: .ts, .tsx, .mts, .cts
Excluidos: *.test.ts, *.spec.ts, *.d.ts, *.config.ts, node_modules/, dist/, build/

Decisiones de diseño

Decisión	Justificación
TypeScript Compiler API (nativa)	Dep `typescript@^6.0.2` ya presente; evita añadir `@babel/parser` u otras
Sin type-checker en v1	El type-checker requiere `tsconfig` + resolución de módulos: coste alto para el backfill inicial; las calls cross-module no resueltas se descartan silenciosamente
Prefix `ts:` en qualified_name	Evita colisiones con el espacio de nombres Python (dot-path) en D1
`replace_app` omitido en backfill	Primera ejecución idempotente; futuros reindexados parciales pueden activarlo por-app

Limitaciones conocidas (v1)

Calls cross-module no resueltas — solo se emiten calls a funciones del mismo módulo o importadas con resolución local (relativa). Las calls a packages externos o a módulos sin nodo destino se descartan con INSERT OR IGNORE.
Funciones anidadas no indexadas — las arrow functions dentro de otras funciones no generan nodo propio; solo se visita su cuerpo para detectar calls del scope padre.
Overloads: si hay varias firmas con el mismo nombre, se toma la primera.
Extensiones sin filesystem check: la resolución de imports relativos (.ts, .tsx) es best-effort sin verificación en disco.

Próximos pasos

v2: integrar type-checker para resolución de calls cross-module.
CI: step de reindexación TS automática tras cada merge que toque .ts/.tsx.
F7.6: monitoring del grafo — alertas si nodes_created=0 en runs sucesivos con cambios TS detectados.

Véase también

[[entity—biblioteca—service—bib-ast-ts]]
[[concept—supercontexto—grafo-de-conocimiento]]
[[entity—biblioteca—tool—bib-index-ast]]
[[decision—20260424—typescript-compiler-api-extractor]]
[[runbook—biblioteca—reindexar-typescript]]