@mailwoman/corpus 10.0.0 → 10.1.0

package/out/fr/adapters/ban/adapter.js

@@ -3,61 +3,52 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `ban`: Base Adresse Nationale CSV adapter (FR street-level).
+ * `ban`: Base Adresse Nationale CSV adapter, street-level over eleven jurisdictions.
  *
- *   Input: a CSV dump from `adresse.data.gouv.fr` (semicolon-separated, ~25M rows nationally). The
- *   adapter only reads the small set of columns needed for the corpus:
+ * Input is a semicolon-separated CSV dump from `adresse.data.gouv.fr`. The adapter reads `numero`
+ * as `house_number`, `rep` as a repetition index appended to it, `nom_voie` as `street`,
+ * `code_postal` as `postcode`, and `nom_commune` as `locality`. BAN carries no region column, so
+ * region is left to the wof-postalcode and wof-admin cross-reference at corpus build time.
  *
- *   - `numero` → `house_number`
- *   - `rep` → repetition index ("bis", "ter") appended to house_number
- *   - `nom_voie` → `street` (full road name; includes the prefix "Rue", "Avenue", etc.)
- *   - `code_postal` → `postcode`
- *   - `nom_commune` → `locality`
+ * IGN publishes one file per INSEE department beside the whole-country extract, and the overseas
+ * departments carry the same 23-column header as the metropolitan rows. A row's country is therefore
+ * derived from `code_insee` rather than asserted by the caller, which reads the same whether the
+ * input is one department's file or an extract spanning several.
  *
- *   `region` and `country` are not in BAN. The adapter stamps `country: "FR"` on every row; region is
- *   left for the wof-postalcode + wof-admin cross-reference at corpus build time (a future pass;
- *   for Phase 1 the row's region is simply absent).
+ * The official BAN is dual-licensed under Licence Ouverte 2.0 and ODbL.
+ * This adapter elects Licence Ouverte 2.0. Its terms permit training with attribution.
+ * It records that license on every row. The model card must include BAN attribution.
  *
- *   License: the official BAN (adresse.data.gouv.fr) is DUAL-licensed — Licence Ouverte 2.0 (Etalab,
- *   attribution-only) OR ODbL (share-alike). We ELECT Licence Ouverte 2.0 (issue #26 Tier B:
- *   allowed for training with attribution; the ODbL option's share-alike obligation would defeat
- *   the proprietary-weights goal). Stamped onto every row as `Licence Ouverte 2.0` — NOT the older
- *   conservative `ODbL-1.0` label, which wrongly read as Tier-C-denied in the corpus license audit.
- *   The model card MUST carry the BAN attribution (Tier B obligation).
- *
- *   The adapter is streaming-aware: `CSVSpliterator.fromAsync` reads the `;`-delimited dump row by
- *   row, so a 25M-row file never sits in memory. Honors `opts.limit` for fixture / smoke runs,
- *   `opts.signal` for cancellation, and `opts.country` for a self-consistency check (errors if
- *   country !== FR).
+ * The adapter streams with `CSVSpliterator.fromAsync`, so a 25M-row file never sits in memory. It
+ * honors `opts.limit` and `opts.signal`. `opts.country` is optional: when set it both rejects a
+ * jurisdiction BAN does not publish and keeps only the rows of the one named.
  */
-import { formatAddressRow } from "@mailwoman/codex/address-format";
+import { formatAddressRow } from "@mailwoman/codex/address/format";
 import { CSVSpliterator } from "spliterator";
-import { stableSourceID } from "#adapters/utils";
-import { decomposeFrStreet } from "#fr/adapters/ban/street-decompose";
+import { UnsupportedCountryError } from "#adapters/errors";
+import { stableSourceID } from "#adapters/source-id";
+import { composeHouseNumber } from "#adapters/street-line";
+import { countryOfInseeCode, INSEE_COUNTRIES } from "#fr/insee-country";
+import { decomposeFrStreet } from "#fr/street-decompose";
+import { SourceRegister } from "#registers";
+import { AddressRole, countDropped, SurfaceOrigin, } from "#types";
 /**
- * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
- * it came from.
+ * Registry id for this adapter.
+ *
+ * Stamped into every row it emits, so a corpus record can be traced back to the dataset it came from.
  */
 export const BAN_ADAPTER_ID = "ban";
-/**
- * Compose `house_number` from `numero` + `rep`. BAN uses `rep` for repetition indices ("bis", "ter", "quater") that
- * follow the house number. Result: `"10 bis"`, `"45"`, etc.
- */
-function composeHouseNumber(numero, rep) {
-    const n = numero.trim();
-    const r = rep.trim();
-    if (!n)
-        return "";
-    return r ? `${n} ${r}` : n;
-}
 export function createBanAdapter() {
     return {
         id: BAN_ADAPTER_ID,
         defaultLicense: "Licence Ouverte 2.0",
-        description: "Base Adresse Nationale (FR): house-number-level street addresses (~25M rows).",
+        addressRole: AddressRole.Premise,
+        register: SourceRegister.BaseAdresseNationale,
+        surface: SurfaceOrigin.Rendered,
+        description: "Base Adresse Nationale: house-number-level street addresses for France and ten overseas jurisdictions.",
         async *rows(opts) {
-            if (opts.country && opts.country !== "FR") {
-                throw new Error(`ban adapter: only FR supported, got country=${opts.country}`);
+            if (opts.country && !INSEE_COUNTRIES.includes(opts.country)) {
+                throw new UnsupportedCountryError(BAN_ADAPTER_ID, INSEE_COUNTRIES, opts.country);
             }
             const rows = CSVSpliterator.fromAsync(opts.inputPath, {
                 normalizeKeys: false,
@@ -69,14 +60,32 @@ export function createBanAdapter() {
                     break;
                 if (opts.limit !== undefined && emitted >= opts.limit)
                     break;
-                const house = composeHouseNumber(record.numero ?? "", record.rep ?? "");
-                const street = (record.nom_voie ?? "").trim();
-                const postcode = (record.code_postal ?? "").trim();
-                const locality = (record.nom_commune ?? "").trim();
-                if (!street || !locality)
+                const country = countryOfInseeCode(record.code_insee ?? "");
+                // A caller that named one jurisdiction gets that jurisdiction's rows,
+                // so one extract spanning several departments can be read once per country.
+                if (opts.country && country !== opts.country)
                     continue;
-                if (!house && !postcode)
+                // BAN stores a repetition index ("bis", "ter", "quater") in `rep`,
+                // which follows the number as a separate word.
+                const house = composeHouseNumber(record.numero ?? "", record.rep ?? "", " ");
+                const street = record.nom_voie ?? "";
+                const postcode = record.code_postal ?? "";
+                const locality = record.nom_commune ?? "";
+                // A row with a number and a commune but no street name is a premise BAN numbers
+                // within the commune, as all 958 of French Polynesia's Pirae rows are.
+                // It renders no street line, so it is refused and counted.
+                if (!street) {
+                    countDropped(opts, "row:street-absent");
                     continue;
+                }
+                if (!locality) {
+                    countDropped(opts, "row:locality-absent");
+                    continue;
+                }
+                if (!house && !postcode) {
+                    countDropped(opts, "row:house-number-and-postcode-absent");
+                    continue;
+                }
                 const decomposed = decomposeFrStreet(street);
                 const components = {};
                 if (house) {
@@ -94,18 +103,20 @@ export function createBanAdapter() {
                 if (locality) {
                     components.locality = locality;
                 }
-                const rendered = formatAddressRow(components, "FR", { singleLine: true });
-                if (!rendered)
+                const rendered = formatAddressRow(components, country, { singleLine: true });
+                if (!rendered) {
+                    countDropped(opts, "row:render-failed");
                     continue;
+                }
                 const { raw, components: aligned } = rendered;
-                const sourceID = record.id?.trim()
-                    ? `${BAN_ADAPTER_ID}-${record.id.trim()}`
-                    : stableSourceID(BAN_ADAPTER_ID, aligned);
+                const sourceID = record.id ? `${BAN_ADAPTER_ID}-${record.id}` : stableSourceID(BAN_ADAPTER_ID, aligned);
                 yield {
                     raw,
                     components: aligned,
-                    country: "FR",
-                    locale: "fr-FR",
+                    country,
+                    // Every jurisdiction BAN publishes writes its addresses in French,
+                    // so the language is constant and the region carries the jurisdiction.
+                    locale: `fr-${country}`,
                     source: BAN_ADAPTER_ID,
                     source_id: sourceID,
                     corpus_version: "",

package/out/fr/adapters/ban/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../../lib/fr/adapters/ban/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../../lib/fr/adapters/ban/adapter.ts"],"names":[],"mappings":"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"}

package/out/fr/adapters/finess/adapter.d.ts

@@ -0,0 +1,276 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `fr-finess-overseas`: the health and social establishments of France's overseas jurisdictions,
+ * read from the FINESS establishment extract that the health ministry publishes on data.gouv.fr.
+ *
+ * Input is the publisher's `etalab-cs1100502-stock-<date>.csv`, the resource titled `Extraction
+ * Finess des Etablissements` on `https://www.data.gouv.fr/datasets/finess-extraction-du-fichier-des-etablissements`.
+ * The file is UTF-8 and semicolon-separated with RFC 4180 quoting. The publisher's description
+ * (`etalab_cs1100502.pdf`) states tab-separated, and the file does not follow it. Line 1 is a comment
+ * (`finess;etalab;111;2026-05-12`) and every other line opens with `structureet`. The adapter reads
+ * the positional columns the description numbers: 4 `rs`, 5 `rslongue`, 8 `numvoie`, 9 `typvoie`, 10
+ * `voie`, 11 `compvoie`, 12 `lieuditbp`, 14 `departement`, 16 `ligneacheminement` and 19
+ * `categetab`, counted from 1. {@linkcode FinessColumn} holds them counted from 0.
+ *
+ * The publisher froze this extract at data dated 2026-05-04 and states on the dataset page that it
+ * will not be updated again. Its successor is the Agence du Numérique en Santé's `FINESS -
+ * Structures` JSON flow, a different schema this adapter does not read.
+ *
+ * ## Which rows are read
+ *
+ * `departement` carries a two-character code, and the overseas ones are `9A` Guadeloupe, `9B`
+ * Martinique, `9C` Guyane, `9D` La Réunion, `9E` Saint-Pierre-et-Miquelon, `9F` Mayotte and `9J`
+ * Wallis-et-Futuna. Saint-Barthélemy and Saint-Martin have no code of their own: their
+ * establishments sit under `9A`, and the postcodes 97133 and 97150 separate them, so the adapter
+ * assigns those two postcodes to BL and MF. A metropolitan row is refused under
+ * {@linkcode FinessRefusal.NotOverseas}, which on the 2026-05-04 extract is most of the file.
+ *
+ * ## Organizations only
+ *
+ * Every FINESS establishment is an organization's site: a hospital, a pharmacy, a laboratory, a
+ * service office. Three categories house the people they serve in a private dwelling. In `462`
+ * Lieux de vie et d'accueil the staff live with the people they receive. A `238` Centre d'accueil
+ * familial spécialisé places patients with host families, as a `236` Service de placement familial
+ * does. An address in those three can be a family's home, so they are refused under
+ * {@linkcode FinessRefusal.FamilyPlacement}, as is an establishment whose name states family
+ * placement or a lieu de vie under another category. A row whose street type is TRE-R35's `CHEZ`,
+ * or whose line opens with `CHEZ`, gives the person whose premises it is and is refused under
+ * {@linkcode FinessRefusal.CareOfPerson}.
+ *
+ * ## The street line
+ *
+ * `numvoie` is the number, `compvoie` its repetition index, `typvoie` a TRE-R35 street-type code and
+ * `voie` the name. The code is expanded by {@linkcode expandFinessVoieType} and written first, as
+ * French addresses write it: `R` and `DE PARIS` print `RUE DE PARIS`. The word takes the name's
+ * case, so an all-capitals name keeps an all-capitals line. A name that already opens with the type
+ * word (`CHE` and `CHEMIN SAFER MORANGE`) is not given it twice, and a name with no code is split by
+ * {@linkcode splitFrenchStreetType}, which reads the BAN adapter's street-type dictionary first.
+ *
+ * `compvoie` is one of `B`, `T`, `Q` or `C`. The first three are bis, ter and quater. `C` is
+ * refused under {@linkcode FinessRefusal.RepetitionIndexAmbiguous}: INSEE's coding reads it as
+ * quinquies, and the national extract carries 133 `C` against 31 `Q`, which is not the ratio of a
+ * fifth repetition to a fourth and reads as a letter suffix entered in the index field.
+ *
+ * A digit in `voie` is refused under {@linkcode FinessRefusal.StreetDigitUnplaced} unless the digits
+ * name the street, as a numbered route (`NATIONALE 2`) or a date (`DU 22 MAI`) does. The number has
+ * its own field, so a digit left in the name is a box, a building or a door: `VALLÉE 3 BP 208`,
+ * `DIAKA BAT A4 PORTE 2`.
+ *
+ * ## The lieu-dit and box line, and the routing line
+ *
+ * `lieuditbp` holds a lieu-dit, a post-office box, or both (`ZA ESPERANCE - BP 26`). The box becomes
+ * `po_box` and the rest `dependent_locality`. A remainder that writes the same place as the locality
+ * or the street is dropped, and one holding a digit is refused under
+ * {@linkcode FinessRefusal.LieuDitDigitUnplaced}, because `1ER ETAGE MONTGERALD` and `VILLA N° 3`
+ * name a floor and a building rather than a place. A remainder that opens with a building, floor or
+ * landmark word (`IMMEUBLE SEMAFA`, `ANGLE DES RUES JEAN JAURES`) is left out of the row and counted
+ * under {@linkcode FinessTrim.LieuDitPremiseDescriptor}, because the row stays an address without it.
+ *
+ * `ligneacheminement` is La Poste's routing line, `97100 BASSE TERRE` or `97331 CAYENNE CEDEX`. It
+ * gives the postcode, the locality as La Poste routes it and the `cedex` phrase, which the codex
+ * layouts of every jurisdiction this adapter emits except French Polynesia print after the locality.
+ *
+ * ## Identity and license
+ *
+ * The row id is content-addressed over the aligned components, so two establishments at one address
+ * under one name are one row. FINESS numbers identify establishments rather than addresses.
+ *
+ * data.gouv.fr publishes the dataset under the license whose id is `fr-lo`, titled `Licence Ouverte /
+ * Open Licence`, and links its text at
+ * `https://www.etalab.gouv.fr/wp-content/uploads/2014/05/Licence_Ouverte.pdf`. That is version 1.0
+ * of October 2011, which grants the reuser the right to « Adapter, modifier, extraire et
+ * transformer à partir de « l'Information », notamment pour créer des « Informations dérivées » »,
+ * « Sous réserve de : Mentionner la paternité de « l'Information » : sa source (a minima le nom du
+ * « Producteur ») et la date de sa dernière mise à jour. » Every row records that license, and
+ * {@linkcode FR_FINESS_ATTRIBUTION} is the credit, which the model card completes with the
+ * extraction date the fetch manifest records.
+ *
+ * The adapter honors `opts.limit`, `opts.signal` and `opts.country`, and counts every refusal
+ * under its reason in `opts.dropped`.
+ */
+import { type CanonicalRow, type CorpusAdapter } from "#types";
+/**
+ * Registry id for this adapter.
+ *
+ * Stamped into every row it emits, so a corpus record can be traced back to the dataset it came from.
+ */
+export declare const FR_FINESS_ADAPTER_ID = "fr-finess-overseas";
+/**
+ * The license data.gouv.fr states for the dataset: `fr-lo`, Licence Ouverte / Open Licence version 1.0.
+ */
+export declare const FR_FINESS_LICENSE = "Licence Ouverte 1.0";
+/**
+ * The credit Licence Ouverte requires: the producer's name, beside the date of the data's last update.
+ */
+export declare const FR_FINESS_ATTRIBUTION = "FINESS, Minist\u00E8re des Solidarit\u00E9s et de la Sant\u00E9, via data.gouv.fr (finess-extraction-du-fichier-des-etablissements)";
+/**
+ * The jurisdiction each overseas `departement` code belongs to.
+ *
+ * `9A` also holds Saint-Barthélemy and Saint-Martin, which {@linkcode FINESS_COUNTRY_BY_POSTCODE} separates.
+ */
+export declare const FINESS_COUNTRY_BY_DEPARTEMENT: Readonly<Record<string, string>>;
+/**
+ * The two Guadeloupe-coded postcodes that belong to separate jurisdictions.
+ */
+export declare const FINESS_COUNTRY_BY_POSTCODE: Readonly<Record<string, string>>;
+/**
+ * Every jurisdiction this adapter can emit.
+ */
+export declare const FR_FINESS_COUNTRIES: readonly string[];
+/**
+ * The establishment categories whose address can be a private dwelling: lieux de vie et
+ * d'accueil, centres d'accueil familial spécialisés and services de placement familial.
+ */
+export declare const FINESS_FAMILY_PLACEMENT_CATEGORIES: ReadonlySet<string>;
+/**
+ * The positions, counted from 0, of the columns this adapter reads, each named by
+ * what it holds with the publisher's column name beside it.
+ */
+export declare const FinessColumn: {
+    /**
+     * `section`, which is `structureet` on every establishment line.
+     */
+    readonly Section: 0;
+    /**
+     * `rs`, the establishment's name, truncated by the publisher to 38 characters.
+     */
+    readonly Name: 3;
+    /**
+     * `rslongue`, the establishment's name up to 60 characters.
+     */
+    readonly LongName: 4;
+    /**
+     * `numvoie`.
+     */
+    readonly StreetNumber: 7;
+    /**
+     * `typvoie`, a TRE-R35 code.
+     */
+    readonly StreetType: 8;
+    /**
+     * `voie`.
+     */
+    readonly StreetName: 9;
+    /**
+     * `compvoie`.
+     */
+    readonly RepetitionIndex: 10;
+    /**
+     * `lieuditbp`.
+     */
+    readonly LieuDitOrBox: 11;
+    /**
+     * `departement`.
+     */
+    readonly Departement: 13;
+    /**
+     * `ligneacheminement`.
+     */
+    readonly RoutingLine: 15;
+    /**
+     * `categetab`.
+     */
+    readonly Category: 18;
+};
+export type FinessColumn = (typeof FinessColumn)[keyof typeof FinessColumn];
+/**
+ * Why a line did not become a row.
+ */
+export declare const FinessRefusal: {
+    /**
+     * The line is not a `structureet` record, as the comment on line 1 is not.
+     */
+    readonly NotEstablishment: "row:not-establishment";
+    /**
+     * The establishment's `departement` is metropolitan.
+     */
+    readonly NotOverseas: "row:not-overseas";
+    /**
+     * The establishment's category places people in a private dwelling.
+     */
+    readonly FamilyPlacement: "row:family-placement";
+    /**
+     * The address is written care of a person.
+     */
+    readonly CareOfPerson: "row:care-of-person";
+    /**
+     * The routing line is not a five-digit postcode followed by a locality and an optional `CEDEX`.
+     */
+    readonly RoutingLineUnparsed: "row:routing-line-unparsed";
+    /**
+     * `typvoie` holds a code neither the codex nor TRE-R35's local transcription resolves.
+     */
+    readonly VoieTypeUnknown: "row:voie-type-unknown";
+    /**
+     * `compvoie` is `C`, which the publisher's coding reads as quinquies and the data reads as a letter.
+     */
+    readonly RepetitionIndexAmbiguous: "row:repetition-index-ambiguous";
+    /**
+     * A house number with no street name to carry it.
+     */
+    readonly NumberWithoutStreet: "row:number-without-street";
+    /**
+     * A street type with no name after it.
+     */
+    readonly StreetNameAbsent: "row:street-name-absent";
+    /**
+     * The street name holds a digit that does not name the street.
+     */
+    readonly StreetDigitUnplaced: "row:street-digit-unplaced";
+    /**
+     * The lieu-dit holds a digit, as a floor, a building or a lot does and a place does not.
+     */
+    readonly LieuDitDigitUnplaced: "row:lieu-dit-digit-unplaced";
+    /**
+     * The address gives a locality and a venue without a street, a lieu-dit or a box.
+     */
+    readonly DeliveryLineAbsent: "row:delivery-line-absent";
+    /**
+     * The jurisdiction's layout does not print every component the row carries.
+     */
+    readonly Unrenderable: "row:unrenderable";
+    /**
+     * Another establishment already produced this exact row.
+     */
+    readonly Duplicate: "row:duplicate";
+};
+export type FinessRefusal = (typeof FinessRefusal)[keyof typeof FinessRefusal];
+/**
+ * Why an admitted row left out a value the record holds.
+ */
+export declare const FinessTrim: {
+    /**
+     * The lieu-dit line names part of a building or a landmark (`IMMEUBLE SEMAFA`), which is not a place.
+     */
+    readonly LieuDitPremiseDescriptor: "component:dependent_locality:premise-descriptor";
+};
+export type FinessTrim = (typeof FinessTrim)[keyof typeof FinessTrim];
+/**
+ * What one record yielded: a row with the values it left out, or the reason it yielded none.
+ */
+export type FinessReading = {
+    readonly admitted: CanonicalRow;
+    readonly trimmed: readonly FinessTrim[];
+} | {
+    readonly refused: FinessRefusal;
+};
+/**
+ * The jurisdiction of an establishment, from its `departement` code and, under `9A`, its postcode.
+ */
+export declare function finessCountry(departement: string, postcode: string): string | null;
+/**
+ * Read one CSV record into a row, or report why it yielded none.
+ *
+ * Exported because the refusal reasons are what this adapter is measured by: a caller reading the
+ * whole extract counts them per reason rather than observing a row count it cannot account for.
+ */
+export declare function readFinessRecord(cells: readonly string[]): FinessReading;
+export declare function createFinessAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const finessAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/fr/adapters/finess/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../lib/fr/adapters/finess/adapter.ts"],"names":[],"mappings":"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"}