Analyze Codebase Workflow
Examinar un repositorio arbitrario para auto-detectar flujos de datos, E/S de archivos y dependencias entre scripts, y luego producir un plan de anotación estructurado para refinamiento manual.
Cuándo Usar
- Al incorporarse a un codebase desconocido y necesitar entender el flujo de datos
- Al iniciar la integración de putior en un proyecto que no tiene anotaciones PUT aún
- Al auditar el pipeline de datos de un proyecto existente antes de documentarlo
- Al preparar un plan de anotación antes de ejecutar
annotate-source-files
Entradas
- Requerido: Ruta al repositorio o directorio fuente a analizar
- Opcional: Subdirectorios específicos en los que centrarse (predeterminado: todo el repositorio)
- Opcional: Lenguajes a incluir o excluir (predeterminado: todos los detectados)
- Opcional: Alcance de detección: solo entradas, solo salidas, o ambas (predeterminado: ambas + dependencias)
Procedimiento
Paso 1: Examinar la Estructura del Repositorio
Identifica los archivos fuente y sus lenguajes para entender qué puede analizar putior.
library(putior)
# List all supported languages and their extensions
list_supported_languages()
list_supported_languages(detection_only = TRUE) # Only languages with auto-detection
# Get supported extensions
exts <- get_supported_extensions()
Usa el listado de archivos para entender la composición del repositorio:
# Count files by extension in the target directory
find /path/to/repo -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
Esperado: Una lista de extensiones de archivos presentes en el repositorio, con conteos. Mapea estos contra get_supported_extensions() para conocer la cobertura.
En caso de fallo: Si el repositorio no tiene archivos que coincidan con las extensiones soportadas, putior no puede auto-detectar flujos de trabajo. Considera si el lenguaje es soportado pero los archivos usan extensiones no estándar.
Paso 2: Verificar la Cobertura de Detección por Lenguaje
Para cada lenguaje detectado, verifica la disponibilidad de patrones de auto-detección.
# Check which languages have auto-detection patterns (18 languages, 902 patterns)
detection_langs <- list_supported_languages(detection_only = TRUE)
cat("Languages with auto-detection:\n")
print(detection_langs)
# Get pattern counts for specific languages found in the repo
for (lang in c("r", "python", "javascript", "sql", "dockerfile", "makefile")) {
patterns <- get_detection_patterns(lang)
cat(sprintf("%s: %d input, %d output, %d dependency patterns\n",
lang,
length(patterns$input),
length(patterns$output),
length(patterns$dependency)
))
}
Esperado: Conteos de patrones impresos para cada lenguaje. R tiene 124 patrones, Python 159, JavaScript 71, etc.
En caso de fallo: Si un lenguaje no devuelve patrones, soporta anotaciones manuales pero no auto-detección. Planifica anotar esos archivos manualmente.
Paso 3: Ejecutar la Auto-Detección
Ejecuta put_auto() en el directorio objetivo para descubrir elementos del flujo de trabajo.
# Full auto-detection
workflow <- put_auto("./src/",
detect_inputs = TRUE,
detect_outputs = TRUE,
detect_dependencies = TRUE
)
# Exclude build scripts and test helpers from scanning
workflow <- put_auto("./src/",
detect_inputs = TRUE,
detect_outputs = TRUE,
detect_dependencies = TRUE,
exclude = c("build-", "test_helper")
)
# View detected workflow nodes
print(workflow)
# Check node count
cat(sprintf("Detected %d workflow nodes\n", nrow(workflow)))
Para repositorios grandes, analiza subdirectorios de forma incremental:
# Analyze specific subdirectories
etl_workflow <- put_auto("./src/etl/")
api_workflow <- put_auto("./src/api/")
Esperado: Un data frame con columnas que incluyen id, label, input, output, source_file. Cada fila representa un paso del flujo de trabajo detectado.
En caso de fallo: Si el resultado está vacío, los archivos fuente pueden no contener patrones de E/S reconocibles. Intenta habilitar el registro de depuración: workflow <- put_auto("./src/", log_level = "DEBUG") para ver qué archivos se escanean y qué patrones coinciden.
Paso 4: Generar el Diagrama Inicial
Visualiza el flujo de trabajo auto-detectado para evaluar la cobertura e identificar brechas.
# Generate diagram from auto-detected workflow
cat(put_diagram(workflow, theme = "github"))
# With source file info for traceability
cat(put_diagram(workflow, show_source_info = TRUE))
# Save to file for review
writeLines(put_diagram(workflow, theme = "github"), "workflow-auto.md")
Esperado: Un diagrama de flujo Mermaid que muestra los nodos detectados conectados por aristas de flujo de datos. Los nodos deben estar etiquetados con nombres significativos de funciones/archivos.
En caso de fallo: Si el diagrama muestra nodos desconectados, la auto-detección encontró patrones de E/S pero no pudo inferir las conexiones. Esto es normal — las conexiones se derivan de hacer coincidir los nombres de archivos de salida con los nombres de archivos de entrada. El plan de anotación (siguiente paso) abordará las brechas.
Paso 5: Producir el Plan de Anotación
Genera un plan estructurado que documente qué se encontró y qué necesita anotación manual.
# Generate annotation suggestions
put_generate("./src/", style = "single")
# For multiline style (more readable for complex workflows)
put_generate("./src/", style = "multiline")
# Copy suggestions to clipboard for easy pasting
put_generate("./src/", output = "clipboard")
Documenta el plan con evaluación de cobertura:
## Annotation Plan
### Auto-Detected (no manual work needed)
- `src/etl/extract.R` — 3 inputs, 2 outputs detected
- `src/etl/transform.py` — 1 input, 1 output detected
### Needs Manual Annotation
- `src/api/handler.js` — Language supported but no I/O patterns matched
- `src/config/setup.sh` — Only 12 shell patterns; complex logic missed
### Not Supported
- `src/legacy/process.f90` — Fortran not in detection languages
### Recommended Connections
- extract.R output `data.csv` → transform.py input `data.csv` (auto-linked)
- transform.py output `clean.parquet` → load.R input (needs annotation)
Esperado: Un plan claro que separa los archivos auto-detectados de los que necesitan anotación manual, con recomendaciones específicas para cada archivo.
En caso de fallo: Si put_generate() no produce salida, asegúrate de que la ruta del directorio sea correcta y contenga archivos fuente en lenguajes soportados.
Validación
-
put_auto()se ejecuta sin errores en el directorio objetivo - El flujo de trabajo detectado tiene al menos un nodo (a menos que el repositorio no tenga E/S reconocible)
-
put_diagram()produce código Mermaid válido del flujo de trabajo auto-detectado -
put_generate()produce sugerencias de anotación para archivos con patrones detectados - Documento del plan de anotación creado con evaluación de cobertura
Errores Comunes
- Escaneo demasiado amplio: Ejecutar
put_auto(".")en la raíz de un repositorio puede incluirnode_modules/,.git/,venv/, etc. Apunta a directorios fuente específicos. - Esperar cobertura completa: La auto-detección encuentra E/S de archivos y llamadas a bibliotecas, no lógica de negocio. Una tasa de cobertura del 40-60% es típica; el resto necesita anotación manual.
- Ignorar dependencias: El flag
detect_dependencies = TRUEcaptura llamadassource(),import,require()que vinculan scripts entre sí. Deshabilitarlo pierde las conexiones entre archivos. - Incompatibilidad de lenguaje: Los archivos con extensiones no estándar (p.ej.,
.Rvs.r,.jsxvs.js) pueden no detectarse. Usaget_comment_prefix()para verificar si una extensión es reconocida. Ten en cuenta que los archivos sin extensión comoDockerfileyMakefilese soportan mediante coincidencia exacta del nombre de archivo. - Repositorios grandes: Para repositorios con más de 100 archivos fuente, analiza por módulo/directorio para mantener los diagramas legibles.
Habilidades Relacionadas
install-putior— requisito previo: putior debe estar instalado primeroannotate-source-files— siguiente paso: añadir anotaciones manuales basadas en el plangenerate-workflow-diagram— generar el diagrama final después de que la anotación esté completaconfigure-putior-mcp— usar herramientas MCP para sesiones de análisis interactivas