Correggi i link interrotti

jamdesk fix ripara ciò che jamdesk broken-links segnala. Legge gli stessi avvisi e riscrive un link quando trova un unico destinatario corretto e chiaro. Lascia invariati i casi ambigui, da verificare manualmente.

Corregge due tipi di link interni interrotti:

• Ancore con refusi: un frammento che è un chiaro errore di battitura di un titolo reale della pagina di destinazione (ad esempio #instalation → #installation)
• Disallineamento delle ancore tra lingue: una pagina tradotta ha rinominato i propri titoli, ma i link in quella lingua puntano ancora al frammento inglese originale (ad esempio /fr/ai/selectors#ai-strategies → /fr/ai/selectors#stratégies-ia)

Passaggio 1: trovare i link interrotti

Esegui jamdesk broken-links per vedere cosa va corretto:

jamdesk broken-links

Esamina l'output. jamdesk fix agisce sugli avvisi in cui riesce ad abbinare un'ancora plausibile a un titolo reale.

Passaggio 2: visualizzare l'anteprima delle correzioni

Esegui con --dry-run per vedere cosa cambierebbe senza scrivere file:

jamdesk fix --dry-run

Output di esempio:

Planned fixes:

  fr/ai/overview.mdx:9
    /fr/ai/selectors#ai-strategies  →  /fr/ai/selectors#stratégies-ia

(dry run — no files written)

Controlla ogni correzione prevista. Se una modifica sembra errata, correggi quel link a mano.

Passaggio 3: applicare le correzioni

Esegui senza --dry-run per applicarle. La CLI chiede conferma:

jamdesk fix

Apply 1 fix(es) to local files? (y/N)

Premi y per scrivere le modifiche. Salta il prompt in CI o negli script con -y:

jamdesk fix -y

Il comando stampa quindi:

Fixed 1 file(s); 0 warning(s) left for manual review.

jamdesk fix lascia da correggere a mano gli avvisi con un destinatario ambiguo.

Passaggio 4: esaminare il diff ed eseguire il commit

Controlla le modifiche prima del commit:

git diff

Verifica che ogni link riscritto punti dove ti aspetti. Poi esegui il commit:

git add -A
git commit -m "fix(docs): auto-fix broken internal links"

Uso con un agente AI

jamdesk fix --json stampa il piano di correzione come un unico documento JSON, destinato a un agente di programmazione come Claude Code. Non scrive file e non pone domande. Le modifiche le esegue l'agente. Richiede CLI 1.1.229 o successiva.

jamdesk fix --json

Output di esempio (abbreviato):

{
  "version": 1,
  "fixes": [
    {
      "type": "broken_link",
      "file": "fr/ai/overview.mdx",
      "line": 9,
      "oldText": "/fr/ai/selectors#ai-strategies",
      "newText": "/fr/ai/selectors#stratégies-ia",
      "resolvedBy": "deterministic"
    },
    {
      "type": "description",
      "file": "setup.mdx",
      "text": "How to set up the CLI.",
      "resolvedBy": "ai"
    }
  ],
  "unfixable": [
    {
      "type": "broken_link",
      "file": "quickstart.mdx",
      "line": 4,
      "link": "/missing",
      "reason": "points at a page that doesn't exist; create it or fix the link"
    }
  ],
  "notes": []
}

Il documento contiene tre liste:

• fixes: le modifiche da apportare. Per un broken_link, sostituisci oldText con newText su quella riga. Una description è un suggerimento AI per il frontmatter della pagina, quindi l'agente dovrebbe mostrartela prima di scriverla.
• unfixable: problemi da correggere a mano, ciascuno con un motivo.
• notes: messaggi dell'esecuzione, ad esempio quando le correzioni AI sono state saltate.

Se l'esecuzione fallisce, l'output è {"version": 1, "error": "..."} e il comando termina con codice 1.

Per iniziare, chiedi al tuo agente qualcosa come: "Esegui jamdesk fix --json, applica le correzioni dei link e mostrami le descrizioni prima di aggiungerle."

Opzioni

E dopo?