france-data-mcp: Skill for Claude Code

Conventions de code (lib, endpoint, boundary)

Déplacé verbatim depuis CLAUDE.md le 2026-09-06 (budget). Source de vérité pour ce périmètre ; CLAUDE.md ne garde que les règles de tête.

Lib (src/) — OSS publiable, pas de Sentry direct.

• Catch jamais silencieux : console.error ou console.warn avec préfixe [france-data-mcp].
• RangeError pour input invalide au boundary public (mappe JSON-RPC -32602).
• LookupResult<T> discriminé pour distinguer "pas trouvé" vs "erreur API".
• Tests _resetXForTesting() pour tout module avec état partagé.
• Lookup PK qui peut retourner ≤ 1 row → expectSingleRow(rpc, rows, identifier, hint) (db-helpers.ts). Source unique du pattern « warne LOUD si N > 1, ne throw pas, picke la première » utilisé par finess_by_num_finess + centres_sante_by_finess. Le hint voyage dans le warn pour préserver les patterns grep ops (PAS reformuler les call-sites).
• Clé de déduplication d'identité = attributs de PERSONNE uniquement, jamais d'attribut de SITE (raison_sociale, adresse). Un PS multi-sites partage une identité ; mettre un attribut de site dans la clé le scinde en faux doublons (régression P1). L'attribut de site voyage dans adresse/sites[].
• Primitives génériques (texte, maths) → core/, jamais sante/. sante/ importe déjà territoire/ : une primitive dans sante/ consommée par territoire/ crée une inversion de couche / cycle. Ré-export depuis l'ancien emplacement pour ne pas casser les consommateurs.
• Résolution point→commune : reverseGeocode (adresse) ≠ communeContainingPoint (frontières) (V0.26.2, territoire/communes.ts). reverseGeocode cherche l'ADRESSE la plus proche → null sur un site sans adresse à proximité (industriel isolé / littoral, ex. Orano La Hague) ALORS que le point est DANS une commune. Tout dérivé d'une commune issu de reverseGeocode (permis Sit@del de dynamique_immobiliere, dept de finess_sirene_coverage_in_radius) DOIT fallback sur communeContainingPoint(lat,lon) (point-dans-polygone geo.api.gouv.fr/communes?lat&lon, frontières IGN AdminExpress). Garde-fou load-bearing length === 1 : sur coords hors-bornes (lat>90…) l'API ignore SILENCIEUSEMENT le filtre géo et renvoie TOUTE la liste alphabétique (34 969 communes, [0]="01001" Ain — faux positif, prouvé prod) → n'exploiter QUE length === 1 (un point ∈ 1 commune ; 0=mer/hors-France, >1=filtre ignoré → null), JAMAIS data[0]. Fail-safe par contrat (catch→null+warn, jamais throw — n'est appelé que sur un chemin déjà dégradé) ; le throw de reverseGeocode (panne IGN réelle) continue de remonter. Seul un point réellement en mer reste sans commune → dégradation propre conservée. Doctrine smoke/test corollaire : gater sur le STATUS de section (couverture.permis === "ok"), JAMAIS sur une donnée métier volatile (logements_autorises_recent > 0) — runSection expose ok dès absence de throw, un count peut valoir 0 légitimement (Fleury-devant-Douaumont : permis="ok" + 0 logement) ; le compte voyage en INFO. scripts/smoke-deploy.mjs encode ces 2 doctrines (gate-sur-status + params boundary {lat,lon,radius_km,naf} jamais {center,radiusKm} = signature lib interne → -32602).
• Resolver SIRET — le best_match privilégie l'établissement ACTIF co-localisé, JAMAIS le score d'adresse seul (V0.16, fix succession M&A — siret-resolver.ts). disambiguateFallbackCandidates applique une étape « actif prime » AVANT le name filter : si ≥ 1 candidat actif est co-localisé avec le FINESS, le best_match est arbitré parmi les actifs ; les SIRET fermés du site restent dans candidates[] (timeline) mais ne sont plus best_match-éligibles. Co-localisation = distance haversine (core/geo-distance.ts) ≤ COLOCATION_RADIUS_M 100 m (V0.16.1, recalibré prod 2026-05-29 — était 50 m), JAMAIS le Dice d'adresse (qui ne discrimine pas le numéro de voie — un voisin au n°48 d'une avenue score 0,90 vs le n°85 du FINESS, prouvé prod). Pourquoi 100 et plus 50 : le géocodage DREES (Lambert93, grossier) décale le point FINESS de plusieurs dizaines de mètres du point BAN de l'adresse — décalage PARTAGÉ par tous les SIRET de cette adresse. Deux repreneurs M&A réels (Cerballiance Aulnay 52,1 m, EYLAU Courbevoie 96,6 m) ressortaient à la distance IDENTIQUE de leur ancien exploitant fermé (même adresse) mais juste au-dessus de 50 m → faux négatif ferme. 100 m couvre ces décalages, sous le voisin-piège testé ~110 m. Garde-fou faux positif inverse au rayon élargi = bande RELATIVE COLOCATION_SAME_SITE_TOLERANCE_M (30 m) : parmi les co-localisés, seuls ceux à ≤ min(distance) + 30 m (« même bâtiment ») sont best_match-éligibles ; un voisin actif d'une AUTRE adresse, plus loin qu'un prédécesseur fermé co-localisé, ne bascule pas le verdict en actif (test garde-fou voisin 80 m / prédécesseur 30 m). NE PAS reverter à 50 m sans relire la preuve prod (les 2 repreneurs redeviendraient invisibles ; le site EYLAU légitime à 46,6 m reste co-localisé dans les deux calibrations). Le fallback géo est aussi armé quand le best_match RPPS est FERMÉ (L1 — sinon le repreneur d'un autre SIREN reste invisible). Champ succession exposé (fait brut — le tool ne dit jamais « rachat »). Garde-fous : cross-source.test.ts (Méca A chemin RPPS / Méca B fallback géo / faux positif inverse) + geo-distance.test.ts. Cadrage durable : docs/plans/verifier-site-actif-succession-fix.md.