tderoussel/vault-doctor

Vault doctor

A maioria dos vaults do Obsidian não tem git e nem undo, e muitos são sincronizados ao vivo via iCloud, OneDrive ou Dropbox. Trate cada escrita como irreversível. Confirme a situação real de backup do vault antes de tocar em qualquer coisa, leia antes de sobrescrever, prefira edições direcionadas a reescritas de arquivo inteiro e nunca execute um loop rápido de escrita — em uma pasta sincronizada, ele produz cópias de conflito.

Varredura

Percorra arquivos .md, pulando node_modules, .git, .obsidian e quaisquer diretórios de build ou temporários que o vault tenha acumulado. Construa o conjunto de alvos de link a partir do nome base de cada arquivo (anexos incluídos, não apenas .md), depois extraia [[alvos]], removendo sufixos |alias, #heading e ^block.

Registre uma linha de base — contagem de notas, alvos quebrados distintos, referências quebradas totais, nomes base duplicados — para que execuções posteriores possam mostrar progresso em vez de repetir o mesmo censo.

Classifique antes de reparar

Uma contagem bruta de links quebrados não é uma lista de defeitos. Classifique cada ocorrência em uma das quatro categorias:

1. Referências entre sistemas — não "corrija". Alguns alvos não são notas do vault: IDs de memória de agente, chaves de ticket ou identificadores de outra ferramenta que por acaso estão escritos em sintaxe de wikilink. Eles nunca serão resolvidos. Convertê-los em texto simples é defensável; criar notas stub para satisfazê-los não é.

2. Documentação de um link quebrado — nunca toque. Algumas notas citam um link quebrado deliberadamente, como exemplo ou como verdade para um exercício ("se sua ferramenta não encontrar isso, sua ferramenta está errada"). Editar isso quebra a coisa que elas ensinam. A sintaxe de wikilink citada dentro da prosa é da mesma classe.

3. Deriva de nome — corrija no alvo, não na origem. Quando muitas referências apontam para um nome curto e a nota está arquivada com um nome mais longo, prefira adicionar aliases: [NomeCurto] ao frontmatter do alvo em vez de editar cada arquivo de referência. Uma edição, um mecanismo nativo do Obsidian, sem risco de danificar o contexto ao redor.

4. Notas genuinamente ausentes. O alvo nunca existiu. Relate-o; não crie automaticamente. Um stub vazio é pior do que um link quebrado porque parece respondido.

A proibição de localizar e substituir

Nunca repare links com um localizar e substituir sem escopo. Uma substituição cega em um vault danificará nomes de pastas, URLs, blocos de código e vocabulários de tags que por acaso contenham a string de pesquisa — e como não há undo, o dano é permanente. Corrija por arquivo, lendo a linha ao redor primeiro.

Outras verificações

• Nomes base duplicados tornam os links ambíguos em todo o vault, porque o Obsidian resolve [[links]] pelo nome do arquivo em todo o vault. O culpado comum é um projeto de código ou árvore de dependências dentro do vault, contribuindo com milhares de arquivos .md fantasmas. Sinalize-o; a correção é mover o projeto para fora do vault ou adicionar uma exclusão. Não exclua nada sem perguntar.

• O frontmatter deve realmente ser analisado. Execute cada bloco através de um analisador YAML real — não olhe apenas. A falha dominante é um escalar simples não citado contendo : (dois-pontos-espaço), que falha nesse caractere e arrasta todas as chaves abaixo dele, tornando todo o bloco invisível para o painel Propriedades do Obsidian e para o Dataview. Uma segunda falha comum: um valor não citado começando com | ou > abre um escalar de bloco YAML.

  Corrigir significa citar valores, o que em uma nota grande e importante pode tocar centenas de chaves — proponha, nunca faça sem ser solicitado, e faça backup do arquivo primeiro. Até que seja corrigido, corresponda à convenção existente (quebrada) em vez de introduzir um segundo estilo; uma chave válida solitária dentro de um bloco inválido não compra nada.

• Tags pertencem ao YAML como uma lista, não como hashtags inline — verifique em relação ao vocabulário real do vault, não a um idealizado. Relate deriva; não remarcule unilateralmente.

• Estado obsoleto — notas carregando marcadores PAUSADO/PARADO/TODO cujo projeto desde então avançou. Relate-as; não as resolva você mesmo.

• Hubs frios — uma nota hub cuja seção de estado mais nova é anterior à atividade mais recente do seu projeto está desatualizada. Relate a lacuna.

Saída

Um relatório, ordenado por categoria, com contagens e referências exatas arquivo:linha. Proponha reparos; faça apenas aqueles que o usuário aprovar.

Declare claramente quais descobertas são verificadas e quais são inferidas a partir do nome — um alvo que parece deriva pode ser uma nota que eles pretendem escrever.