diskd-ai/codespaces — Mapa de Creencias para Descubrimiento de…

Codespaces — Descubrimiento de Arquitectura Mediante Mapa de Creencias

Consulta .belief_map.sexp para descubrir módulos, límites y dependencias antes de leer los archivos fuente. Nunca leas código a ciegas — consulta primero el grafo.

Scripts

Esta habilidad incluye scripts de Python. Ejecútalos desde el directorio base de la habilidad:

• scripts/belief_search.py — consulta el grafo del mapa de creencias
• scripts/build_belief_map.py — genera el mapa de creencias a partir del código fuente
• scripts/build_infra_topology.py — extrae hechos de topología de Kustomize, Helm y Terraform
• scripts/git_descendants.py — encuentra todos los commits descendientes de HEAD (o de una referencia dada)

Nunca uses copias locales del proyecto de estos scripts — pueden estar desactualizadas y generar JSON en lugar de sexp.

Prerrequisito

Localiza el mapa de creencias. Si está ausente, constrúyelo:

ls .belief_map.sexp belief_map.sexp 2>/dev/null
# Construir: pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
python3 scripts/build_belief_map.py          # incremental ~5s
python3 scripts/build_belief_map.py --full   # reconstrucción completa ~30s

Flujo de Trabajo Obligatorio: Consultar Antes de Leer Código

Para trabajo de código no trivial, ejecuta una consulta al mapa de creencias antes de rg, find, sed, cat, nl, abrir directorios o leer archivos fuente. La habilidad solo es útil cuando se usa como primer paso de delimitación, no como confirmación después de haber inspeccionado el código fuente.

Primer paso rápido cuando la tarea tiene una palabra clave clara:

python3 scripts/belief_search.py quick "palabra-clave"

quick busca el primer módulo que coincide y ejecuta inmediatamente analyze. Úsalo para obtener archivos de límite, dependencias, dependencias inversas, capas y violaciones en un solo paso. Si quick devuelve el módulo incorrecto o no encuentra coincidencia, usa el flujo explícito search -> analyze que se muestra a continuación.

Paso 1 — Encontrar el ID del módulo:

python3 scripts/belief_search.py search "palabra-clave"
python3 scripts/belief_search.py entity NombreEntidad

Usa search o entity para localizar el ID del módulo. Los IDs de módulo son rutas relativas completas como pki-service/src/modules/ca/ca.service, no códigos cortos como ps34. El mapa de creencias puede contener internamente IDs cortos de mapa de rutas, pero se resuelven automáticamente — siempre pasa cadenas legibles con formato de ruta. NO adivines ni inventes IDs de módulo — confírmalos siempre primero con search.

Paso 2 — Analizar el módulo (haz esto INMEDIATAMENTE, no opcionalmente):

python3 scripts/belief_search.py analyze <id-del-módulo>

analyze es el comando PRINCIPAL. Devuelve el contexto completo: archivos de límite, dependencias, dependencias inversas, capa arquitectónica y violaciones. Ejecútalo siempre antes de leer cualquier fuente.

Paso 3 — Lee solo los archivos de límite listados en la salida de analyze.

Paso 4 — NO leas directorios enteros. Si el límite muestra 2-3 archivos relevantes, lee solo esos archivos. Ignora todo lo demás en el directorio.

Referencia de Comandos

Comando	Propósito	Ejemplo
search "<patrón>"	Búsqueda regex en el grafo (encontrar IDs de módulo)	search "operative.*service"
analyze <id>	Análisis completo del módulo (comando PRINCIPAL)	analyze drive/modules/drive/drive_schema
quick <palabra-clave>	Buscar + analizar la primera coincidencia (atajo)	quick operatives
boundary <id>	Archivos a leer para un cambio	boundary operatives.service
boundary <id> --files-only	Solo rutas de archivos (compacto)	boundary operatives.service --files-only
entity <Nombre>	Buscar definiciones + referencias	entity DrivePath
deps <id> [profundidad]	Árbol de dependencias salientes	deps operatives.service 3
rdeps <id> [profundidad]	Radio de explosión (quién depende de esto)	rdeps drive_schema 2
flow <id> <fn>	Trazar flujo de llamadas/datos	flow drive_api fetchFiles
module <id>	Módulo único con aristas	module operatives.controller
`boundaries [id	all]`	Verificar violaciones arquitectónicas
`invariants [id	all]`	Verificar violaciones de convenciones de nombres
layers	Mostrar todos los módulos por capa	layers
find_function <nombre>	Buscar definiciones de funciones/métodos	find_function createOrder
find_type <nombre>	Buscar definiciones de tipos/clases/interfaces/enums	find_type DriveDbCommitResponse
find_callchain <origen> <destino> [profundidad]	Trazar ruta de llamada entre funciones	find_callchain createOrder processPayment
find_callers <fn> [profundidad]	Quién llama a esta función	find_callers handleRequest 3
find_calls <fn> [profundidad]	Qué llama esta función	find_calls createOrder 2
grep_functions <patrón>	Buscar cuerpos de funciones en el código fuente	grep_functions "validate.*input"
diff_functions [ref]	Funciones cambiadas en git diff	diff_functions HEAD~3
query '<sexp>'	Consulta Scheme componible	query '(count (boundary "X"))'
repl	REPL Scheme interactivo	repl

Referencia Rápida: Consultas con rg

Cuando necesites búsquedas rápidas y específicas sin invocar el script de Python, consulta el mapa de creencias directamente con rg. El constructor incluido escribe .belief_map.sexp; si un repositorio aún usa el belief_map.sexp heredado, sustituye ese nombre de archivo en los comandos a continuación:

# Todos los hechos sobre un módulo
rg 'drive/modules/drive_db/api ' .belief_map.sexp

# Quién importa un módulo
rg 'imports .* drive/modules/commons/result' .belief_map.sexp

# Qué importa un módulo
rg 'imports drive/modules/drive_db/api' .belief_map.sexp

# Todas las referencias a una entidad
rg 'DriveDbCommitResponse' .belief_map.sexp

# Todas las clases en un repositorio
rg '^\(cls drive/' .belief_map.sexp

# Aristas de flujo de datos
rg 'data-flow' .belief_map.sexp

Estos one-liners son útiles para comprobaciones rápidas. Para salida estructurada y análisis completo, usa los comandos del script de Python.

Notación de Salida

Toda la salida son hechos en formato S-expression, uno por línea. Consulta references/sexp-notation.md para el formato completo.

Patrones clave:

(boundary <mod> :lang py :file <ruta> :purpose "<desc>")
(boundary-dep <mod> <dep> :lang ts :file <ruta> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <ruta> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Nombre> <línea> :lang py :file <ruta>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<razón>")
(result <módulo-o-ruta>)
(result-count 42)

Valores de :lang: py = Python (snake_case), ts = TypeScript (camelCase), tsx = TSX (PascalCase).

Lenguaje de Consultas Scheme

Compón consultas para análisis complejos. Consulta references/scheme-queries.md para la referencia completa.

Esenciales:

(boundary "id")                ; destino + dependencias + dependencias inversas (límite de cambio)
(entity "Nombre")             ; módulos que definen la entidad
(deps "id" profundidad)       ; dependencias salientes
(rdeps "id" profundidad)      ; dependencias inversas
(find-function "nombre")      ; módulos con definiciones de función coincidentes
(find-type "nombre")          ; módulos con definiciones de tipo coincidentes
(find-callers "fn" profundidad) ; módulos que llaman a una función
(find-calls "fn" profundidad) ; módulos a los que llama una función
(intersect A B)                ; intersección de conjuntos
(filter SET "patrón")         ; filtro regex
(files SET)                    ; resolver a rutas de archivo
(count SET)                    ; contar miembros
(violations)                   ; módulos con violaciones de límite
(layer "id")                  ; capa arquitectónica de un módulo

Patrón de Plan de Análisis

Antes de modificar código, compón un plan a partir de consultas:

; 1. Delimitar
(boundary "operatives.service")
(count (boundary "operatives.service"))

; 2. Restricciones arquitectónicas
(violations "operatives.service")
(layer "operatives.service")

; 3. Límites entre lenguajes
(filter (refs-to "DrivePath") "app-service")

; 4. Reducir a archivos accionables
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))

; 5. Después de cambios: verificar
(violations "operatives.service")

Ejemplos de Activación

Usa esta habilidad antes de leer código fuente para:

• Investigaciones de causa raíz que mencionen servicios, APIs, trabajos, eventos, flujos de UI o comportamientos fallidos.
• Preguntas entre servicios o entre módulos, incluyendo "¿cómo llama X a Y?" y "¿dónde se almacena esto?"
• Aclaración en Redmine cuando la respuesta depende del comportamiento del código.
• Revisiones de arquitectura, análisis de impacto, cambios en contratos públicos o comprobaciones de radio de explosión.
• Revisiones de cambios no triviales en staged cuando la dirección de dependencia o la propiedad del módulo importa.

No la fuerces para tareas de solo commit, resúmenes de git-log, ejecuciones manuales de demostración/servidor, pruebas puramente en navegador o análisis de sesión.

Recuperación de Errores

Si un comando devuelve (error no-match ...):

1. NO reintentes con el mismo ID ni adivines otro ID
2. Ejecuta search con una palabra clave más amplia para encontrar el ID de módulo correcto
3. Usa el campo :suggestions si está presente — lista IDs de módulo similares

# Incorrecto: adivinar IDs
python3 scripts/belief_search.py analyze ps34        # falla: ps34 es un ID corto de mapa de rutas
python3 scripts/belief_search.py analyze ca.service  # falla: ruta incompleta

# Correcto: buscar primero, luego usar la ruta completa de los resultados
python3 scripts/belief_search.py search "ca.*service"
# La salida muestra: pki-service/src/modules/ca/ca.service
python3 scripts/belief_search.py analyze pki-service/src/modules/ca/ca.service

Antipatrones

• Adivinar IDs de módulo. Los IDs de módulo son rutas relativas completas (ej., pki-service/src/modules/ca/ca.service). Códigos cortos como ps34 son IDs internos de mapa de rutas y no deben usarse directamente. Siempre ejecuta search primero.
• Construir pero nunca consultar. Construir el mapa de creencias y luego nunca ejecutar search, analyze o boundary no aporta ningún valor.
• Consultar después de leer código fuente. La primera lectura de código fuente debe provenir de las líneas boundary-file en la salida de analyze.
• Leer .belief_map.sexp como un archivo completo. Usa search, analyze o rg para consultar hechos específicos.
• Saltarse el mapa de creencias para tareas entre módulos. Siempre consulta el grafo para entender los límites antes de leer archivos fuente.
• Leer todos los archivos de un directorio. Cuando el límite muestra 2-3 archivos, lee solo esos.
• Usar scripts locales del proyecto. Siempre usa los scripts incluidos en esta habilidad. Las copias del proyecto pueden generar JSON en lugar de sexp.

Reconstrucción del Grafo

python3 scripts/build_belief_map.py          # incremental (~5s)
python3 scripts/build_belief_map.py --full   # reconstrucción completa (~30s)
python3 scripts/build_belief_map.py ./drive  # único sub-repositorio
python3 scripts/build_belief_map.py --lsp    # con jerarquía de llamadas LSP (~1-5min)

Reconstruye después de cambios estructurales (añadir/eliminar archivos, cambiar importaciones, añadir clases).

Topología de Infraestructura

Extrae topología de servicios de archivos Kustomize, Helm y Terraform. Este script requiere PyYAML (pip3 install pyyaml).

python3 scripts/build_infra_topology.py                    # detección automática de todo IaC
python3 scripts/build_infra_topology.py --kustomize .      # solo kustomize
python3 scripts/build_infra_topology.py --helm ./charts    # solo helm charts
python3 scripts/build_infra_topology.py --terraform ./infra # solo terraform
python3 scripts/build_infra_topology.py --append .belief_map.sexp  # fusionar en el grafo

Genera aristas infra-node, k8s-depends, k8s-service, helm-depends, tf-depends e infra-maps. Consulta con:

rg 'infra-node' .belief_map.sexp                  # todos los servicios
rg 'k8s-depends' .belief_map.sexp                 # dependencias de servicios
rg 'infra-node.*:component database' .belief_map.sexp  # todas las bases de datos
rg 'infra-maps.*app-service' .belief_map.sexp     # mapeo infra -> código fuente