@mailwoman/corpus 9.4.0 → 10.1.0

package/out/es/tools/fetch/navarra.js

@@ -0,0 +1,316 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Harvest the INSPIRE Addresses archives the Gobierno de Navarra publishes into the directory
+ * `#es/adapters/navarra/adapter` reads.
+ *
+ * The service is one ATOM document rather than two levels. The service document at
+ * `https://filescartografia.navarra.es/2_CARTOGRAFIA_TEMATICA/2_7_CATASTRO/2_7_3_INSPIRE_ATOM/2_7_3_3_AD/Addresses_ServiceATOM_Navarra.xml`
+ * lists one entry per partition, and each entry links that partition's zipped GML directly.
+ * Measured 2026-10-03: the document answered http 200 with 671,131 bytes holding 272 entries,
+ * sha256 `6971dd61d87e2fc047e953e956b09c6cc88aaa92e16ffb3bbc4750a1edb1ab60`.
+ *
+ * Four properties of this service decide the harvest's shape.
+ *
+ * 1. **The archive link is the `enclosure` link, and the `alternate` link is not it.** Each entry
+ *    carries six links, three of which address the same archive under `enclosure`, `section` and
+ *    `alternate`. The entry's *first* `alternate` link is the relative href
+ *    `Addresses_DatasetATOM_Navarra.xml`, which is the dataset feed, so a reader taking the first
+ *    `alternate` link downloads an ATOM document in place of the archive. This harvest takes
+ *    `enclosure` and refuses an entry that carries none.
+ * 2. **An entry leaves its own area unstated.** Every one of the 272 entries is titled
+ *    `Address Navarra` and every `<id>` is empty, so the archive's own file name,
+ *    `AD_Navarra_<n>.gml.zip`, is the only statement of which partition an entry offers. The
+ *    numbers are not contiguous: the 272 published partitions run from 1 to 908. A partition
+ *    therefore cannot be selected by place from the feed, and this module claims no mapping from a
+ *    partition number to a municipality.
+ * 3. **The `length` attribute is one number repeated.** All 272 entries claim 34,987 bytes, while
+ *    partition 1 delivers 7,476. Every byte count this module records is counted off the delivered
+ *    body.
+ * 4. **Every entry states one `<updated>`, which is also the feed's own.** All 272 read
+ *    `2026-04-14T12:06:58Z`, so the value dates the publication rather than the file. It is still
+ *    the freshness signal a re-run compares, because a new edition moves it. A skip requires the
+ *    feed to state a value: where it states none, both sides read an empty string and an equality
+ *    test would keep an archive of unknown age for as long as the feed stayed silent.
+ *
+ * A full harvest is 273 requests and roughly 10 MB: a systematic sample of 10 of the 272 archives
+ * on 2026-10-03 ran from 7,476 to 112,830 bytes. The harvest is bound by round trips rather than by
+ * bandwidth and is dispatched serially through one `APIClient` at
+ * {@linkcode ES_NAVARRA_REQUEST_INTERVAL_MS}.
+ *
+ * The archives stay compressed. `#es/adapters/navarra/adapter` reads the GML member through
+ * `inspireGMLChunks`, which inflates from the archive, and partition 1's member is 307,117 bytes
+ * against its archive's 7,476.
+ */
+import { APIClient, assertNoOGCServiceException } from "@mailwoman/core/api";
+import { ByteFormatter } from "@mailwoman/core/fs/formatters";
+import { tryStat } from "@mailwoman/core/fs/readers";
+import { makeDirectories } from "@mailwoman/core/fs/writers";
+import { sha256File } from "@mailwoman/core/hash";
+import { stringifyJSON } from "@mailwoman/core/json";
+import { PathBuilder } from "path-ts";
+import { ES_NAVARRA_ADAPTER_ID, ES_NAVARRA_LICENSE } from "#es/adapters/navarra/adapter";
+import { feedChunks, linkWithRel, readAtomFeed } from "#tools/fetch/atom";
+import { loadCollectionFiles, writeManifest } from "#tools/fetch/download";
+import { downloadZipArchive } from "#tools/fetch/zip-archive";
+/**
+ * The ATOM service document, which lists one zipped GML partition per entry.
+ */
+export const ES_NAVARRA_SERVICE_FEED_URL = "https://filescartografia.navarra.es/2_CARTOGRAFIA_TEMATICA/2_7_CATASTRO/2_7_3_INSPIRE_ATOM/2_7_3_3_AD/Addresses_ServiceATOM_Navarra.xml";
+/**
+ * The attribution the publisher's license requires.
+ *
+ * Every entry's `<rights>` elects `Creative Commons Attribution 4.0 International (CC BY 4.0)`,
+ * whose attribution clause requires naming the creator, so a model card carrying
+ * this source credits the publisher.
+ */
+export const ES_NAVARRA_ATTRIBUTION = "Gobierno de Navarra";
+/**
+ * The minimum spacing between two requests to `filescartografia.navarra.es`, in milliseconds.
+ *
+ * Four requests per second against one government host.
+ * The publisher states no rate limit, and a full harvest is 273 requests.
+ */
+export const ES_NAVARRA_REQUEST_INTERVAL_MS = 250;
+/**
+ * The directory the harvest writes under, which is the adapter's `inputPath`.
+ */
+const SLUG = ES_NAVARRA_ADAPTER_ID;
+/**
+ * How many archives are written between two manifest writes.
+ *
+ * The manifest is what makes an interrupted harvest resumable.
+ * At this interval an interruption re-fetches at most this many archives that are already on disk.
+ */
+const MANIFEST_INTERVAL = 25;
+/**
+ * A partition archive's file name, `AD_Navarra_1.gml.zip`.
+ */
+const ARCHIVE_FILENAME = /^AD_Navarra_(\d+)\.gml\.zip$/iu;
+/**
+ * The partitions the service document lists.
+ *
+ * @throws When the document holds no entry, when an entry carries no `enclosure` link, when a
+ * linked archive is not named `AD_Navarra_<n>.gml.zip`, or when two entries name one archive.
+ * Each of those would otherwise write zero archives while reporting a completed run.
+ */
+export function readESNavarraServiceFeed(feed) {
+    if (!feed.entries.length) {
+        throw new Error(`${ES_NAVARRA_SERVICE_FEED_URL}: the service document holds no <entry>, so the partitions it offers ` +
+            `could not be read`);
+    }
+    const partitions = [];
+    const seen = new Set();
+    for (const entry of feed.entries) {
+        // The `enclosure` link rather than the first `alternate` link: an entry's first
+        // `alternate` link is the relative dataset-feed href, and downloading it would
+        // store an ATOM document under an archive's name.
+        const link = linkWithRel(entry.links, "enclosure");
+        if (!link?.href) {
+            throw new Error(`${ES_NAVARRA_SERVICE_FEED_URL}: an entry titled ${stringifyJSON(entry.title)} carries no ` +
+                `rel="enclosure" link, so its archive could not be read`);
+        }
+        const filename = link.href.slice(link.href.lastIndexOf("/") + 1);
+        const numbered = ARCHIVE_FILENAME.exec(filename);
+        if (!numbered) {
+            throw new Error(`${ES_NAVARRA_SERVICE_FEED_URL}: an entry links ${stringifyJSON(filename)}, which is not named ` +
+                `AD_Navarra_<n>.gml.zip. Every entry is titled ${stringifyJSON(entry.title)}, so the file name ` +
+                `is the only statement of which partition the entry offers.`);
+        }
+        if (seen.has(filename)) {
+            throw new Error(`${ES_NAVARRA_SERVICE_FEED_URL}: ${stringifyJSON(filename)} is listed twice, so one of the two ` +
+                `archives would overwrite the other`);
+        }
+        seen.add(filename);
+        partitions.push({
+            partition: numbered[1],
+            title: entry.title.trim(),
+            updated: entry.updated,
+            archiveURL: link.href,
+            filename,
+        });
+    }
+    return partitions;
+}
+/**
+ * Whether the archive recorded for one partition is still the one the feed describes.
+ *
+ * A skip requires the feed to state an `<updated>` value.
+ * Where it states none, both sides read an empty string and an equality test would hold,
+ * which would keep an archive of unknown age for as long as the feed stayed silent.
+ */
+async function isCurrent(recorded, partition, path, verifyDigests) {
+    if (!recorded || !partition.updated || recorded.feed_updated !== partition.updated)
+        return false;
+    const stat = await tryStat(path);
+    if (!stat || stat.size !== recorded.bytes)
+        return false;
+    // The digest check reads the whole file rather than its metadata, which is why it is opt-in.
+    if (!verifyDigests)
+        return true;
+    return (await sha256File(path)) === recorded.sha256;
+}
+/**
+ * The partitions this run considers, and the numbers a caller named that the feed does not list.
+ *
+ * A number the caller asked for and the service document does not list is returned
+ * rather than dropped, because a partition that is not published is a different
+ * condition from a selection that holds no partition.
+ */
+function selectPartitions(listed, options) {
+    let selected = listed;
+    const unknown = [];
+    if (options.partitions) {
+        const byNumber = new Map(listed.map((partition) => [partition.partition, partition]));
+        const found = [];
+        for (const number of options.partitions) {
+            const partition = byNumber.get(number);
+            if (partition) {
+                found.push(partition);
+            }
+            else {
+                unknown.push(number);
+            }
+        }
+        selected = found;
+    }
+    if (options.limit !== undefined) {
+        selected = selected.slice(0, options.limit);
+    }
+    return { selected, unknown };
+}
+/**
+ * Harvest the partitions the service document lists into `options.outputDir`.
+ *
+ * The client is injected so the harvest is testable without the network and so a caller decides
+ * the pacing. {@linkcode fetchESNavarra} is the registry entry point and supplies both.
+ *
+ * @returns What was fetched, what the feed states is already recorded, and which partitions failed.
+ * @throws When the service document lists no partition, which would otherwise answer
+ * `{fetched: 0, skipped: 0, failed: 0}` and read to a caller as a completed fetch of an empty publisher.
+ */
+export async function harvestESNavarra(client, options) {
+    const { report, signal } = options;
+    const destDir = PathBuilder.from(options.outputDir);
+    const manifestPath = destDir("MANIFEST.json");
+    report?.(`=== ${SLUG}: reading ${ES_NAVARRA_SERVICE_FEED_URL}`);
+    const { data: serviceXML } = await client.fetch({
+        method: "GET",
+        url: ES_NAVARRA_SERVICE_FEED_URL,
+        responseType: "text",
+        timeout: 120_000,
+        signal,
+    });
+    // The service document shares the http 200 an exception report arrives on.
+    assertNoOGCServiceException(serviceXML, `${SLUG} service document`);
+    const feed = await readAtomFeed(feedChunks(serviceXML));
+    const listed = readESNavarraServiceFeed(feed);
+    report?.(`  ${listed.length} partitions listed`);
+    const wanted = selectPartitions(listed, options);
+    report?.(`  ${wanted.selected.length} selected for this run`);
+    // Resolved before the directory is made, so a publisher that answers an exception
+    // report leaves no empty source directory behind.
+    await makeDirectories(destDir);
+    const previous = await loadCollectionFiles(manifestPath);
+    const files = new Map();
+    // An entry for a partition this run does not consider is carried through,
+    // so a bounded run never drops what an earlier run recorded.
+    for (const [filename, entry] of previous) {
+        files.set(filename, entry);
+    }
+    let fetched = 0;
+    let skipped = 0;
+    const failedCodes = [...wanted.unknown];
+    for (const unknown of wanted.unknown) {
+        report?.(`  ✗ partition ${unknown} is not listed in the service document`);
+    }
+    const writeHarvestManifest = async () => {
+        const manifest = {
+            source: SLUG,
+            source_url: ES_NAVARRA_SERVICE_FEED_URL,
+            license: ES_NAVARRA_LICENSE,
+            attribution: ES_NAVARRA_ATTRIBUTION,
+            downloaded_at: new Date().toISOString(),
+            partitions_listed: listed.length,
+            files: [...files.values()].toSorted((left, right) => Number(left.partition) - Number(right.partition)),
+        };
+        await writeManifest(manifestPath, manifest);
+    };
+    for (const partition of wanted.selected) {
+        if (signal?.aborted)
+            break;
+        const dest = destDir(partition.filename);
+        if (await isCurrent(files.get(partition.filename), partition, dest, options.verifyDigests ?? false)) {
+            skipped++;
+            continue;
+        }
+        try {
+            const delivered = await downloadZipArchive(client, {
+                url: partition.archiveURL,
+                dest,
+                timeout: 600_000,
+                signal,
+            });
+            files.set(partition.filename, {
+                partition: partition.partition,
+                filename: partition.filename,
+                source_url: partition.archiveURL,
+                downloaded_at: new Date().toISOString(),
+                sha256: delivered.sha256,
+                bytes: delivered.bytes,
+                feed_updated: partition.updated,
+                last_modified: delivered.lastModified,
+            });
+            fetched++;
+            report?.(`  ✓ ${partition.filename} ${ByteFormatter.formatIEC(delivered.bytes)} sha256=${delivered.sha256}`);
+        }
+        catch (error) {
+            report?.(`  ✗ ${partition.partition}: ${error instanceof Error ? error.message : String(error)}`);
+            failedCodes.push(partition.partition);
+            continue;
+        }
+        if (fetched % MANIFEST_INTERVAL === 0) {
+            await writeHarvestManifest();
+        }
+    }
+    await writeHarvestManifest();
+    report?.(`=== ${SLUG} summary`);
+    report?.(`fetched: ${fetched}`);
+    report?.(`skipped: ${skipped} (the feed states the publication date already recorded)`);
+    report?.(`failed:  ${failedCodes.length}`);
+    return { fetched, skipped, failed: failedCodes.length, failedCodes };
+}
+/**
+ * The path `#es/adapters/navarra/adapter` reads, given the root a fetch wrote under.
+ *
+ * The adapter takes one archive or a directory holding them, and a harvest writes a directory.
+ */
+export function esNavarraInputPath(outRoot) {
+    return outRoot(SLUG);
+}
+/**
+ * Harvest the Gobierno de Navarra's INSPIRE Addresses partitions into `<outRoot>/es-navarra/`.
+ *
+ * Re-runnable: a partition whose recorded publication date is still the one the feed states,
+ * and whose archive is still on disk at the recorded length, costs no request.
+ */
+export async function fetchESNavarra(options, report) {
+    await using client = new APIClient({
+        displayName: SLUG,
+        minRequestIntervalMs: options.minRequestIntervalMs ?? ES_NAVARRA_REQUEST_INTERVAL_MS,
+        retry: true,
+    });
+    // Awaited rather than returned: `await using` disposes the client when this scope exits,
+    // and a disposed `APIClient` refuses every later request.
+    return await harvestESNavarra(client, {
+        outputDir: options.outRoot(SLUG),
+        partitions: options.partitions,
+        limit: options.limit,
+        verifyDigests: options.verifyDigests,
+        signal: options.signal,
+        report,
+    });
+}
+//# sourceMappingURL=navarra.js.map

package/out/es/tools/fetch/navarra.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navarra.js","sourceRoot":"","sources":["../../../../lib/es/tools/fetch/navarra.ts"],"names":[],"mappings":"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"}

package/out/fi/adapters/ryhti/adapter.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `ryhti`: Suomen ympäristökeskus' Ryhti built-environment address CSV adapter, covering Finland
+ * and Åland.
+ *
+ * Input is the comma-separated `open_address.csv.gz`, decompressed, that SYKE publishes for the
+ * whole country at `https://paikkatiedot.ymparisto.fi/geoserver/www/open_address.csv.gz`.
+ * The file quotes fields, so the reader is quote-aware: a split on `,` misaligns every column
+ * and reports 460 distinct `municipality_number` values where 308 exist.
+ * Which columns are quoted is a property of the edition rather than of the format.
+ * The edition served on 2026-10-02, `last-modified` `Thu, 1 Oct 2026 05:20:03 GMT` and
+ * `content-length` 351288399, quotes `address_number`, the two number-part columns,
+ * `municipality_number`, `postal_code` and `location_srid`, leaving the header and
+ * every name column bare.
+ *
+ * A row's country comes from `municipality_number` rather than from the caller. Åland is part of
+ * Finland and its sixteen municipalities carry Finnish municipality numbers, so one national file
+ * holds both jurisdictions and {@linkcode ALAND_MUNICIPALITIES} is what separates them.
+ *
+ * The street and the house number are read from the publisher's own part columns rather than from
+ * its inline address text.
+ * `address_name_fin` is the whole of `address_fin` or a space-delimited prefix of it, and the four
+ * number-part columns reproduce the publisher's inline number.
+ * Measured over the first 292,293 rows of the 2026-10-02 edition: 278,262 rows populate both
+ * columns, 0 of them place `address_name_fin` anywhere but at the head of `address_fin`, and the
+ * composed number equals the inline remainder byte for byte on all 265,830 numbered rows.
+ * No row publishes inline address text with both name columns empty,
+ * so reading the name columns loses no address.
+ *
+ * `address_number` is not a house number. It is a 1-based ordinal over the addresses sharing one
+ * `building_key`, which is how a corner building's several frontages are numbered, and it holds nine
+ * distinct values across the file. The adapter ignores it.
+ *
+ * The file is bilingual, and which column carries which language depends on the municipality. On
+ * mainland Finland `address_name_fin` is the Finnish name and `address_name_swe` the Swedish one. On
+ * Åland the `*_fin` columns, where populated at all, hold the **Swedish** name: `address_fin` reads
+ * `Skogshyddsvägen 11`.
+ * So the adapter prefers `*_swe` on Åland and `*_fin` on the mainland, and emits one row per
+ * published record from the preferred language's columns.
+ * `locale` names the language of the name it emitted rather than the language of the column that
+ * name came from, which gives three values.
+ * `fi-FI` is a mainland record named in `address_name_fin`.
+ * `sv-FI` is a mainland record that populates `address_name_swe` alone, which is the form a
+ * Swedish-speaking municipality publishes.
+ * `sv-AX` is every Åland record, because the Swedish columns are the populated ones there and the
+ * `*_fin` columns hold the Swedish name where they are populated at all.
+ * A mainland record's Swedish name, where the record publishes both, is not emitted as a second
+ * row: a record is one premise, and `CanonicalRow` carries one written surface.
+ *
+ * SYKE's metadata record `{DBD610F4-3392-44CD-B601-BAE8FA547A57}` grants CC BY 4.0 for its open data
+ * and the register's two elected decisions for this file record `CC-BY-4.0` in their `spdx` field, so
+ * the adapter records that license on every row. SYKE states the attribution it wants as
+ * `Lähde: Syke Ryhti`, and the model card must carry it.
+ *
+ * The adapter streams with `CSVSpliterator.fromAsync`, so the 3.8M-row file never sits in memory. It
+ * honors `opts.limit`, `opts.signal` and `opts.country`.
+ */
+import { 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 RYHTI_ADAPTER_ID = "ryhti";
+/**
+ * The sixteen `municipality_number` values of Åland's municipalities.
+ *
+ * Every other number in the file belongs to a mainland Finnish municipality.
+ * The file holds 308 distinct values, and these sixteen cover 32,518 of its 3,862,609 rows.
+ *
+ * The column is a zero-padded three-digit string, so a reader compares the padded form.
+ */
+export declare const ALAND_MUNICIPALITIES: ReadonlySet<string>;
+/**
+ * Every jurisdiction this adapter emits, checked against a caller's `--country`.
+ */
+export declare const RYHTI_COUNTRIES: readonly string[];
+/**
+ * The four columns that hold a house number, declared as one shape because
+ * {@linkcode composeRyhtiHouseNumber} reads these four columns and derives the number from them.
+ */
+interface RyhtiNumberParts {
+    number_part_of_address_number: string;
+    number_part_of_address_number2: string;
+    subdivision_letter_of_address_number: string;
+    subdivision_letter_of_address_number2: string;
+}
+/**
+ * The country a row belongs to, read from its municipality number.
+ *
+ * The comparison is against the zero-padded three-digit form the file publishes,
+ * and a shorter value is padded rather than refused, so `35` reads as Brändö.
+ */
+export declare function countryOfFinnishMunicipality(municipalityNumber: string): string;
+/**
+ * The house number, composed from the four part columns.
+ *
+ * SYKE splits `41a` into a number part and a subdivision letter, and a range such
+ * as `184-183b` across a second pair of the same two columns.
+ * The second pair is appended after a hyphen when either of its halves is populated.
+ *
+ * @returns The composed number, or an empty string for a row with no number at all,
+ * which a caller treats as a named place rather than assigning it a number.
+ */
+export declare function composeRyhtiHouseNumber(record: Partial<RyhtiNumberParts>): string;
+export declare function createRyhtiAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const ryhtiAdapter: CorpusAdapter;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/out/fi/adapters/ryhti/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../lib/fi/adapters/ryhti/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AASH,OAAO,EAAuD,KAAK,aAAa,EAAiB,MAAM,QAAQ,CAAA;AAE/G;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAiBnD,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAiB,CAAA;AAmB9D;;;GAGG;AACH,UAAU,gBAAgB;IACzB,6BAA6B,EAAE,MAAM,CAAA;IACrC,8BAA8B,EAAE,MAAM,CAAA;IACtC,oCAAoC,EAAE,MAAM,CAAA;IAC5C,qCAAqC,EAAE,MAAM,CAAA;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAI/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAcjF;AAkDD,wBAAgB,kBAAkB,IAAI,aAAa,CA8FlD;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,eAAuB,CAAA"}