tderoussel/vault-doctor

Vault doctor

La mayoría de las bóvedas de Obsidian no tienen git ni deshacer, y muchas se sincronizan en vivo a través de iCloud, OneDrive o Dropbox. Trata cada escritura como irreversible. Confirma la situación real de copia de seguridad de la bóveda antes de tocar nada, lee antes de sobrescribir, prefiere ediciones dirigidas en lugar de reescrituras completas de archivos, y nunca ejecutes un bucle de escritura rápida, ya que en una carpeta sincronizada produce copias de conflicto.

Escaneo

Recorre los archivos .md, omitiendo node_modules, .git, .obsidian y cualquier directorio de compilación o basura que la bóveda haya acumulado. Construye el conjunto de destinos de enlaces a partir de cada nombre base de archivo (incluyendo archivos adjuntos, no solo .md), luego extrae [[destinos]], eliminando los sufijos |alias, #encabezado y ^bloque.

Registra una línea base: recuento de notas, destinos rotos distintos, referencias rotas totales, nombres base duplicados, para que ejecuciones posteriores puedan mostrar cambios en lugar de repetir el mismo censo.

Clasificar antes de reparar

Un recuento bruto de enlaces rotos no es una lista de defectos. Clasifica cada acierto en uno de cuatro cubos:

1. Referencias entre sistemas — no "arreglar". Algunos destinos no son notas de la bóveda en absoluto: IDs de memoria del agente, claves de tickets o identificadores de otra herramienta que por casualidad están escritos con sintaxis de wikilink. Nunca se resolverán. Convertirlos a texto plano es defendible; crear notas stub para satisfacerlos no lo es.

2. Documentación de un enlace roto — nunca tocar. Algunas notas citan deliberadamente un enlace roto, como ejemplo o como verdad fundamental para un ejercicio ("si tu herramienta no encuentra esto, tu herramienta está mal"). Editar esto rompe lo que enseñan. La sintaxis de wikilink citada dentro de la prosa pertenece a la misma clase.

3. Deriva de nombre — arreglar en el destino, no en el origen. Cuando muchas referencias apuntan a un nombre corto y la nota está archivada bajo uno más largo, prefiere agregar aliases: [NombreCorto] al frontmatter del destino en lugar de editar cada archivo de referencia. Una edición, un mecanismo nativo de Obsidian, sin riesgo de estropear el contexto circundante.

4. Notas genuinamente faltantes. El destino nunca existió. Reportarlo; no lo crees automáticamente. Un stub vacío es peor que un enlace roto porque parece que ya está respondido.

La prohibición de buscar y reemplazar

Nunca repares enlaces con una búsqueda y reemplazo sin alcance. Un reemplazo ciego en toda la bóveda estropeará nombres de carpeta, URLs, bloques de código y vocabularios de etiquetas que por casualidad contengan la cadena de búsqueda, y como no hay deshacer, el daño es permanente. Corrige por archivo, leyendo primero la línea circundante.

Otras comprobaciones

• Nombres base duplicados hacen que los enlaces sean ambiguos en toda la bóveda, porque Obsidian resuelve [[enlaces]] por nombre de archivo en toda la bóveda. El culpable habitual es un proyecto de código o árbol de dependencias dentro de la bóveda, que aporta miles de archivos .md fantasma. Señálalo; la solución es mover el proyecto fuera de la bóveda o agregar una exclusión. No elimines nada sin preguntar.

• El frontmatter debe analizarse realmente. Ejecuta cada bloque a través de un analizador YAML real; no lo evalúes a ojo. El fallo dominante es un escalar simple sin comillas que contiene : (dos puntos y espacio), que falla en ese carácter y arrastra a todas las claves debajo de él, haciendo que todo el bloque sea invisible para el panel de Propiedades de Obsidian y para Dataview. Un segundo fallo común: un valor sin comillas que comienza con | o > abre un escalar de bloque YAML.

  Arreglarlo significa poner valores entre comillas, lo que en una nota grande y crítica puede afectar a cientos de claves — propónlo, nunca lo hagas sin previo aviso, y haz una copia de seguridad del archivo primero. Hasta que se arregle, mantén la convención existente (rota) en lugar de introducir un segundo estilo; una clave válida solitaria dentro de un bloque inválido no compra nada.

• Las etiquetas pertenecen al YAML como una lista, no como hashtags en línea; compáralas con el vocabulario real de la bóveda, no con uno idealizado. Reporta la deriva; no reetiquetes unilateralmente.

• Estado obsoleto — notas que llevan marcadores PAUSADO/DETENIDO/POR HACER cuyo proyecto ya ha avanzado. Repórtalas; no las resuelvas tú mismo.

• Hubs fríos — una nota hub cuya sección de estado más reciente es anterior a la última actividad de su proyecto está desactualizada. Reporta la brecha.

Salida

Un informe, ordenado por cubo, con recuentos y referencias exactas archivo:línea. Propón reparaciones; realiza solo aquellas que el usuario apruebe.

Indica claramente qué hallazgos están verificados y cuáles son inferidos a partir del nombre — un destino que parece deriva puede ser una nota que el usuario planea escribir.