Les limites & les mensonges externes, ou où la preuve s'arrête The limits & external lies, or where the proof stops

Tout l'édifice repose sur des déclarations — et une déclaration peut mentir.The whole edifice rests on declarations — and a declaration can lie.

Le système de types est une preuve. Mais toute preuve part d'axiomes — et ici, les axiomes sont les déclarations qu'on n'a pas écrites : les .d.ts des bibliothèques, les @types tiers, les declare posés sur du JavaScript nu. Un .d.ts peut affirmer n'importe quoi sur du code qui fait autre chose. Si une déclaration annonce number là où la lib renvoie un string, le compilateur te croit vert — et le runtime plante. Ta garantie de type n'est jamais plus forte que la déclaration la plus faible sur le chemin.The type system is a proof. But every proof starts from axioms — and here, the axioms are the declarations you didn't write: libraries' .d.ts, third-party @types, the declare laid over bare JavaScript. A .d.ts can assert anything about code that does otherwise. If a declaration claims number where the lib returns a string, the compiler tells you green — and the runtime crashes. Your type guarantee is never stronger than the weakest declaration on the path.

// dans un .d.ts fourni par la lib (ou un @types tiers) :
declare function parseAmount(raw: string): number;

const total = parseAmount(input);   // le compilateur croit : number
total.toFixed(2);                    // 💥 la lib renvoie en réalité un string → crash
// le .d.ts a AFFIRMÉ 'number' ; le JavaScript réel n'a jamais tenu cette promesse

// On ne fait pas confiance aveugle à une déclaration externe douteuse :
const raw: unknown = parseAmount(input);     // on retype en unknown (7.1)
const total = AmountSchema.parse(raw);        // on VALIDE à la frontière (7.2)
total.toFixed(2);                             // ✓ prouvé à l'exécution, pas sur parole

skipLibCheck est presque toujours actif — donc les .d.ts ne sont pas vérifiés.skipLibCheck is almost always on — so the .d.ts are not checked.

Deux surprises qui se renforcent. D'abord, skipLibCheck traîne dans la plupart des configs de démarrage, par souci de vitesse — et il dit au compilateur de ne pas vérifier les fichiers de déclaration. Les .d.ts sur lesquels toute ton application s'appuie ne sont donc même pas contrôlés pour leur cohérence interne. Ensuite, declare est par nature une affirmation : il pose un type sur du JavaScript sans jamais le confronter au code réel. C'est un as à l'échelle du module — utile, parfois indispensable, mais c'est un acte de foi, pas une preuve.Two surprises that reinforce each other. First, skipLibCheck lingers in most starter configs, for speed — and it tells the compiler not to check declaration files. The .d.ts your whole application relies on aren't even checked for internal consistency. Second, declare is by nature an assertion: it lays a type over JavaScript without ever confronting it with the real code. It's an as at module scale — useful, sometimes indispensable, but it's an act of faith, not a proof.

// Présent dans la plupart des tsconfig de démarrage :
{ "compilerOptions": { "skipLibCheck": true } }
// → TypeScript NE VÉRIFIE PAS les .d.ts (les tiens compris).
//   Les déclarations sur lesquelles toute l'app s'appuie ne sont pas contrôlées.

On l'active pour accélérer tsc (9.2) et contourner des .d.ts tiers mal fichus — un compromis souvent raisonnable. Mais il faut le savoir : les déclarations qui fondent tes garanties ne sont pas relues par le compilateur. La base de la preuve n'est, elle-même, pas prouvée.You enable it to speed up tsc (9.2) and work around broken third-party .d.ts — often a reasonable trade. But you must know it: the declarations underpinning your guarantees aren't rechecked by the compiler. The proof's base is, itself, unproven.

Trois sources de types externes, une chaîne de confiance — aussi forte que son maillon faible.Three sources of external types, one chain of trust — as strong as its weakest link.

Les types des dépendances arrivent par trois voies. Les .d.ts fournis avec la lib, versionnés avec elle — les plus fiables. Les @types/* (DefinitelyTyped), maintenus par la communauté, séparément de la lib — donc susceptibles de décaler quand la lib évolue. Et l'absence totale de types, qu'on comble par un declare maison — un as de module. Dans tous les cas, le même principe : ton code est vérifié contre ces déclarations, mais ta garantie réelle ne vaut que celle du maillon le plus faible de la chaîne.Dependency types arrive by three routes. The .d.ts shipped with the lib, versioned with it — the most reliable. The @types/* (DefinitelyTyped), community-maintained, separately from the lib — hence liable to drift when the lib evolves. And the total absence of types, filled by a homemade declare — an as at module scope. In every case, the same principle: your code is checked against these declarations, but your real guarantee is worth only that of the chain's weakest link.

// D'où viennent les types des dépendances :
import { z } from "zod";          // .d.ts FOURNI par la lib (souvent fiable, versionné avec elle)
import _ from "lodash";           // @types/lodash : maintenu par la COMMUNAUTÉ, peut décaler
import legacy from "old-lib";     // aucun type → 'declare' à écrire soi-même (un as de module)

// La chaîne de confiance — ta garantie = le maillon le plus faible :
//
//   TON code  ──fait confiance──▶  .d.ts / @types  ──affirme──▶  JavaScript réel
//      (vérifié)                    (PAS vérifié si skipLibCheck)   (jamais confronté)
//
// une seule déclaration fausse sur le chemin, et toute la preuve en aval est creuse.

Le @types obsolète : le compilateur est vert, et le runtime plante.The stale @types: the compiler is green, and the runtime crashes.

Le contre-exemple final : faire une confiance aveugle à un @types dont la version a décroché de la lib réelle. La lib passe en v4, sa fonction change de signature ; mais @types reste en v2 et déclare encore l'ancienne forme. Le compilateur vérifie ton code contre une déclaration périmée : tout est vert. À l'exécution, la vraie lib fait autre chose, et ça casse — un bug que le typage promettait justement d'empêcher. Le réflexe : aligner les versions, préférer les types fournis avec la lib, et pour une frontière critique, valider au runtime plutôt que croire un .d.ts.The final counter-example: blindly trusting an @types whose version drifted from the real lib. The lib goes to v4, its function changes signature; but @types stays at v2 and still declares the old shape. The compiler checks your code against a stale declaration: all green. At runtime, the real lib does otherwise, and it breaks — a bug typing was precisely meant to prevent. The reflex: align versions, prefer the types shipped with the lib, and for a critical boundary, validate at runtime rather than believe a .d.ts.

// package.json : la lib a bondi, ses types non
"dependencies":    { "date-lib": "^4.0.0" },     // v4 : parse() renvoie un objet Date
"devDependencies": { "@types/date-lib": "^2.1.0" } // v2 : déclare encore 'string'

const d = parse("2026-12-01");   // le compilateur croit : string (selon @types v2)
d.trim();                        // ✓ VERT — sur un string, trim() est parfaitement légitime
//   mais v4 rend un Date : « d.trim is not a function » 💥
//   le build ne prouve que la cohérence avec le .d.ts, pas avec la lib

Le compilateur fait son travail parfaitement — contre la mauvaise carte. Un build vert ne prouve que la cohérence avec les déclarations, pas avec la lib réelle. Quand @types ment par retard, le typage ne te protège plus : il t'endort.The compiler does its job perfectly — against the wrong map. A green build only proves consistency with the declarations, not with the real lib. When @types lies by lagging, typing no longer protects you: it lulls you.