@mailwoman/corpus 9.4.0 → 10.1.0

package/out/fi/adapters/ryhti/adapter.js

@@ -0,0 +1,244 @@
+/**
+ * @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 { formatAddressRow } from "@mailwoman/codex/address/format";
+import { CSVSpliterator } from "spliterator";
+import { UnsupportedCountryError } from "#adapters/errors";
+import { stableSourceID } from "#adapters/source-id";
+import { composeHouseNumber } from "#adapters/street-line";
+import { SourceRegister } from "#registers";
+import { AddressRole, 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.
+ */
+export 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 const ALAND_MUNICIPALITIES = new Set([
+    "035", // Brändö
+    "043", // Eckerö
+    "060", // Finström
+    "062", // Föglö
+    "065", // Geta
+    "076", // Hammarland
+    "170", // Jomala
+    "295", // Kumlinge
+    "318", // Kökar
+    "417", // Lemland
+    "438", // Lumparland
+    "478", // Mariehamn
+    "736", // Saltvik
+    "766", // Sottunga
+    "771", // Sund
+    "941", // Vårdö
+]);
+/**
+ * Every jurisdiction this adapter emits, checked against a caller's `--country`.
+ */
+export const RYHTI_COUNTRIES = ["FI", "AX"];
+/**
+ * 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 function countryOfFinnishMunicipality(municipalityNumber) {
+    const padded = municipalityNumber.trim().padStart(3, "0");
+    return ALAND_MUNICIPALITIES.has(padded) ? "AX" : "FI";
+}
+/**
+ * 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 function composeRyhtiHouseNumber(record) {
+    const first = composeHouseNumber(record.number_part_of_address_number ?? "", record.subdivision_letter_of_address_number ?? "");
+    if (!first)
+        return "";
+    const secondNumber = (record.number_part_of_address_number2 ?? "").trim();
+    const secondLetter = (record.subdivision_letter_of_address_number2 ?? "").trim();
+    if (!secondNumber && !secondLetter)
+        return first;
+    return `${first}-${secondNumber}${secondLetter}`;
+}
+/**
+ * The surface to emit for one record, or `undefined` for a record that names no street.
+ *
+ * On Åland the Swedish columns are preferred, and the Finnish ones are read as Swedish.
+ * That is the language they hold there.
+ *
+ * On the mainland the Finnish columns are preferred.
+ * The Swedish ones stand in where `address_name_fin` is empty.
+ * That is the form a Swedish-speaking municipality publishes.
+ *
+ * A language whose name column is empty names no street.
+ * Seven mainland rows publish an `address_swe` of a bare number with an empty `address_name_swe`.
+ * This refuses them rather than giving them an empty street.
+ */
+function surfaceOf(record, country) {
+    const finnish = {
+        street: (record.address_name_fin ?? "").trim(),
+        locality: (record.postal_office_fin ?? "").trim(),
+    };
+    const swedish = {
+        street: (record.address_name_swe ?? "").trim(),
+        locality: (record.postal_office_swe ?? "").trim(),
+    };
+    if (country === "AX") {
+        const preferred = swedish.street ? swedish : finnish;
+        return preferred.street ? { ...preferred, language: "sv" } : undefined;
+    }
+    if (finnish.street)
+        return { ...finnish, language: "fi" };
+    return swedish.street ? { ...swedish, language: "sv" } : undefined;
+}
+export function createRyhtiAdapter() {
+    return {
+        id: RYHTI_ADAPTER_ID,
+        defaultLicense: "CC-BY-4.0",
+        addressRole: AddressRole.Premise,
+        register: SourceRegister.RyhtiBuildingAddress,
+        surface: SurfaceOrigin.Rendered,
+        description: "Ryhti built-environment building address data (Suomen ympäristökeskus): street-level addresses for Finland and Åland.",
+        async *rows(opts) {
+            if (opts.country && !RYHTI_COUNTRIES.includes(opts.country)) {
+                throw new UnsupportedCountryError(RYHTI_ADAPTER_ID, RYHTI_COUNTRIES, opts.country);
+            }
+            const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+                normalizeKeys: false,
+            });
+            let emitted = 0;
+            let unnamed = 0;
+            try {
+                for await (const record of rows) {
+                    if (opts.signal?.aborted)
+                        break;
+                    if (opts.limit !== undefined && emitted >= opts.limit)
+                        break;
+                    const country = countryOfFinnishMunicipality(record.municipality_number ?? "");
+                    // A caller that named one jurisdiction gets that jurisdiction's rows,
+                    // so the one national file can be read once per country.
+                    if (opts.country && country !== opts.country)
+                        continue;
+                    const surface = surfaceOf(record, country);
+                    if (!surface) {
+                        unnamed += 1;
+                        continue;
+                    }
+                    const postcode = (record.postal_code ?? "").trim();
+                    if (!postcode && !surface.locality)
+                        continue;
+                    const house = composeRyhtiHouseNumber(record);
+                    const components = {};
+                    if (house) {
+                        components.house_number = house;
+                    }
+                    components.street = surface.street;
+                    if (postcode) {
+                        components.postcode = postcode;
+                    }
+                    if (surface.locality) {
+                        components.locality = surface.locality;
+                    }
+                    const rendered = formatAddressRow(components, country, { singleLine: true });
+                    if (!rendered)
+                        continue;
+                    const { raw, components: aligned } = rendered;
+                    const key = (record.address_key ?? "").trim();
+                    const sourceID = key ? `${RYHTI_ADAPTER_ID}-${key}` : stableSourceID(RYHTI_ADAPTER_ID, aligned);
+                    yield {
+                        raw,
+                        components: aligned,
+                        country,
+                        locale: `${surface.language}-${country}`,
+                        source: RYHTI_ADAPTER_ID,
+                        source_id: sourceID,
+                        corpus_version: "",
+                        license: "CC-BY-4.0",
+                    };
+                    emitted++;
+                }
+            }
+            finally {
+                if (unnamed > 0) {
+                    process.stderr.write(`  ryhti: ${unnamed} rows name no street in either language and were dropped, ${emitted} kept\n`);
+                }
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const ryhtiAdapter = createRyhtiAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/fi/adapters/ryhti/adapter.js.map

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

package/out/fi/tools/fetch/ryhti.d.ts

@@ -0,0 +1,206 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Download Suomen ympäristökeskus' Ryhti built-environment address CSV for the `ryhti` adapter.
+ *
+ * SYKE publishes the whole country, Åland included, as one gzipped CSV at
+ * `https://paikkatiedot.ymparisto.fi/geoserver/www/open_address.csv.gz`. There is no per-region
+ * distribution and no API, so the harvest is one transfer rather than a paging loop.
+ *
+ * The acquisition belongs under a `tools/` root. `@mailwoman/corpus` is one of the
+ * `TOOLING_PACKAGES` in `dependency-cruiser.config.mjs`, which keep their tooling under `lib/`, so
+ * this module sits beside `#fr/tools/fetch/ban` rather than in an `sdk/` root the workspace does
+ * not declare.
+ *
+ * SYKE's metadata record `{DBD610F4-3392-44CD-B601-BAE8FA547A57}` grants CC BY 4.0, which the
+ * address-source register elects, and states the attribution as `Lähde: Syke Ryhti`. The manifest
+ * records both, and `#fi/adapters/ryhti/adapter` records the license on every row.
+ *
+ * Four measured properties decide what this module does:
+ *
+ * 1. **The file is republished daily and its length changes with it.** `HEAD` answered
+ *    `content-length: 351290196` and `last-modified: Fri, 2 Oct 2026 05:20:14 GMT` on 2026-10-02,
+ *    against `351288399` and `Thu, 1 Oct 2026 05:20:03 GMT` the day before. So the re-run check is
+ *    a `HEAD` compared against the manifest, which costs one small request instead of 351 MB, and
+ *    neither number is written into this module as a constant.
+ * 2. **The host ignores `Range`.** `bytes=0-4095` answers HTTP 200 with no `content-range` and the
+ *    whole `content-length`, and `accept-ranges` is absent, so a resumed transfer is not available
+ *    and an interrupted one restarts. {@linkcode resumableDownload} would refuse the response.
+ * 3. **This module moves bytes and decodes none of them.** The body is streamed to disk compressed, then
+ *    decompressed stream to stream, so no chunk boundary is ever interpreted as a character
+ *    boundary. A `chunk.toString("utf8")` per gzip chunk produces a U+FFFD at every boundary that
+ *    splits a multi-byte character, and 60,014,592 decompressed bytes of this file were scanned for
+ *    `EF BF BD` with 0 found: the replacement characters such a reader reports are its own.
+ * 4. **The decompressed CSV is what the adapter can read.** `#fi/adapters/ryhti/adapter` hands
+ *    `opts.inputPath` to `CSVSpliterator.fromAsync`, which reads the bytes as they are on disk, so
+ *    a path to the `.gz` would be parsed as CSV over gzip bytes. The `.gz` is therefore removed once the CSV is
+ *    written: 793 MB of readable input instead of 351 MB plus a reader the adapter does not have.
+ *    A caller that wants the compressed copy kept passes
+ *    {@linkcode FetchRyhtiOptions.keepCompressed}, which costs 1.14 GB for both.
+ */
+import { APIClient } from "@mailwoman/core/api";
+import { type PathBuilderLike } from "path-ts";
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download";
+/**
+ * The one file SYKE publishes for this theme.
+ */
+export declare const FI_RYHTI_CSV_URL = "https://paikkatiedot.ymparisto.fi/geoserver/www/open_address.csv.gz";
+/**
+ * The decompressed file the adapter reads.
+ */
+export declare const FI_RYHTI_CSV_FILENAME = "open_address.csv";
+/**
+ * The license the register elects for this file.
+ */
+export declare const FI_RYHTI_LICENSE = "CC-BY-4.0";
+/**
+ * The attribution SYKE states for its open data, which the model card must carry.
+ */
+export declare const FI_RYHTI_ATTRIBUTION = "L\u00E4hde: Syke Ryhti";
+/**
+ * The columns `#fi/adapters/ryhti/adapter` indexes by name.
+ *
+ * The header is checked against these rather than against a column count, because the adapter reads a
+ * subset by name and a renamed column would otherwise reach it as an empty string on every row.
+ * Which columns the publisher quotes is a property of the edition — the 2026-10-02
+ * edition quotes `address_number`, the two number-part columns, `municipality_number`,
+ * `postal_code` and `location_srid` and leaves the header and every name column bare —
+ * so the check reads a quote-aware split rather than assuming either form.
+ */
+export declare const FI_RYHTI_REQUIRED_COLUMNS: readonly string[];
+/**
+ * What the manifest records about the one file.
+ *
+ * {@linkcode SourceManifest}'s five fields describe the decompressed CSV,
+ * which is what the adapter reads and what the digest covers.
+ * The three added fields describe the transfer, and they are what the re-run
+ * check compares before it downloads 351 MB.
+ */
+export interface RyhtiManifest extends SourceManifest {
+    license: string;
+    attribution: string;
+    /**
+     * The `Last-Modified` the host served the compressed file under, or `null` where it served none.
+     */
+    last_modified: string | null;
+    /**
+     * The `content-length` the host stated for the compressed file, or `null` where it stated none.
+     */
+    compressed_bytes: number | null;
+    /**
+     * The columns the header named when this file was downloaded, in order.
+     *
+     * Recorded rather than counted, so a later edition's added, removed or renamed
+     * column is a diff against this list rather than a count that moved.
+     */
+    columns: readonly string[];
+}
+/**
+ * What the host states about the file without sending it.
+ */
+export interface RyhtiHead {
+    lastModified: string | null;
+    contentLength: number | null;
+    contentType: string | null;
+}
+/**
+ * Read what the host states about the file.
+ *
+ * Through `APIClient`, which is the interface for a repeated request with a small response.
+ * The body itself is not taken this way: `APIClient` buffers a response, and this one is 351 MB.
+ *
+ * A header the host does not send is reported as `null` rather than raised on,
+ * and the caller then downloads rather than treating the absence as a match.
+ */
+export declare function readRyhtiHead(client: Pick<APIClient, "fetch">, url?: string): Promise<RyhtiHead>;
+/**
+ * The header line's column names, read from the decompressed file.
+ *
+ * The file is comma-separated, so {@linkcode readDelimitedHeader} is called without a delimiter.
+ *
+ * @throws When the file holds no row at all, so an empty or truncated file reports itself
+ * rather than reading as a file with no columns.
+ */
+export declare function readRyhtiColumns(path: PathBuilderLike): Promise<readonly string[]>;
+/**
+ * Refuse a header that does not name every column the adapter indexes.
+ *
+ * @throws Naming the columns that are absent, so a renamed column is a reported failure
+ * rather than an empty string on every row the adapter emits.
+ */
+export declare function assertRyhtiColumns(columns: readonly string[], context: string): void;
+export interface DownloadRyhtiOptions {
+    /**
+     * Where the CSV and the manifest are written.
+     * The CSV inside it is the adapter's `inputPath`.
+     */
+    outputDir: PathBuilderLike;
+    /**
+     * Keep the compressed copy beside the CSV.
+     *
+     * The adapter reads the CSV, so the default removes the archive once the CSV is written.
+     * Keeping both holds 1.14 GB for the one file.
+     */
+    keepCompressed?: boolean;
+    /**
+     * Re-read the CSV's sha256 on a re-run instead of comparing its byte count.
+     *
+     * The default compares the recorded byte count against the file's size, which is one `stat`.
+     * This re-hashes 793 MB.
+     */
+    verifyDigest?: boolean;
+    /**
+     * Download even where the `HEAD` agrees with the manifest.
+     */
+    force?: boolean;
+    /**
+     * Attempts after the first for the one transfer.
+     * Defaults to three.
+     *
+     * The host ignores `Range`, so each attempt starts the 351 MB again.
+     */
+    retries?: number;
+    /**
+     * Pause between attempts, in milliseconds.
+     * Defaults to `DEFAULT_RETRY_DELAY_MS`.
+     */
+    retryDelayMs?: number;
+    signal?: AbortSignal;
+    report?: (line: string) => void;
+}
+export type FetchRyhtiOptions = BaseFetchOptions & Omit<DownloadRyhtiOptions, "outputDir" | "report">;
+/**
+ * The directory `#fi/adapters/ryhti/adapter` reads under a fetch root.
+ */
+export declare function ryhtiInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike;
+/**
+ * Download the Ryhti address CSV into `options.outputDir` and leave it beside its manifest.
+ *
+ * The client is injected so the re-run check is testable without the network, and so a caller
+ * decides the retry policy. {@linkcode fetchRyhti} is the registry entry point and supplies one.
+ *
+ * Re-runnable: a run whose `HEAD` matches the manifest's recorded modification time and compressed
+ * length, and whose CSV is still on disk at the recorded length, makes no request for the body.
+ *
+ * A full fetch is two requests, the `HEAD` and the body, and 351,290,196 compressed bytes as
+ * measured on 2026-10-02, decompressing to a CSV this module measures rather than predicts.
+ */
+export declare function downloadRyhti(client: Pick<APIClient, "fetch">, options: DownloadRyhtiOptions): Promise<FetchSummary>;
+/**
+ * Download the Ryhti address CSV into `<outRoot>/ryhti/`.
+ *
+ * The registry entry point.
+ * `#fi/adapters/ryhti/adapter` is pointed at {@linkcode ryhtiInputPath},
+ * the `open_address.csv` inside that directory, rather than at the directory itself.
+ */
+export declare function fetchRyhti(options: FetchRyhtiOptions, report?: (line: string) => void): Promise<FetchSummary>;
+/**
+ * Decompress one gzip file to another path, stream to stream.
+ *
+ * Exported because it is the step the U+FFFD report came out of, and a test exercises it
+ * directly: a multi-byte character split across two gzip chunks must arrive whole.
+ */
+export declare function decompressToCSV(source: PathBuilderLike, destination: PathBuilderLike): Promise<void>;
+//# sourceMappingURL=ryhti.d.ts.map

package/out/fi/tools/fetch/ryhti.d.ts.map

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