@mailwoman/corpus 10.0.0 → 10.1.0

package/out/tools/fetch/atom.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Reads an INSPIRE predefined-dataset ATOM feed into its links and entries.
+ *
+ *   Several member states serve the Addresses (AD) theme as an ATOM feed rather than as a WFS, so
+ *   this is the shape a fetcher reads before it downloads anything. The elements are the same at
+ *   both levels of a two-level service: a service document's entry points at a dataset feed, and
+ *   that feed's entries point at files, and both are `<entry>` with `<link>` children.
+ *
+ *   Parsed with `@mailwoman/core/html/elements` rather than matched with a pattern, because a feed
+ *   needs the two things a pattern handles badly. An entry's open tag carries attributes
+ *   (`xml:lang`), and an href escapes the ampersand between its query parameters, so a reader has to
+ *   keep attributes and decode entities. XML mode is required: a feed's links self-close, and HTML
+ *   mode leaves them open.
+ *
+ *   Feed-level links are told from entry-level links by the parser rather than by position. Asking
+ *   for `link` and `entry` together yields a `link` only where it is not already inside an `entry`,
+ *   because capture runs to the outermost requested element's close.
+ */
+/**
+ * One `<link>` of a feed or of one of its entries.
+ *
+ * `rel` is lower-cased, since it is a controlled value, while `href`, `type`
+ * and `title` are kept as the publisher wrote them.
+ */
+export interface AtomLink {
+    href: string;
+    /**
+     * The relation, lower-cased, or an empty string where the link states none.
+     */
+    rel: string;
+    /**
+     * The media type the link advertises, or `null` where it advertises none.
+     *
+     * A publisher may advertise the type of the data inside the file rather than of the file:
+     * ČÚZK writes `application/gml+xml` on a link that serves `application/zip`.
+     */
+    type: string | null;
+    title: string | null;
+    /**
+     * The byte count the link claims, or `null` where it claims none or claims a non-numeric one.
+     *
+     * Never taken as the size of a download.
+     * Denmark's feed understates its file by 23 times, so every byte count a fetcher
+     * records is counted off the delivered body instead.
+     */
+    length: number | null;
+}
+/**
+ * One `<entry>` of a feed.
+ */
+export interface AtomEntry {
+    /**
+     * The entry's `<id>`, which is a URI rather than a name.
+     */
+    id: string;
+    title: string;
+    /**
+     * The entry's `<updated>`, as the feed spells it, or an empty string where it states none.
+     *
+     * Whether this describes the data or the feed is a property of the publisher: Denmark's is
+     * older than the file it serves, while ČÚZK's equals the file's `Last-Modified` to the second.
+     * A fetcher that reads it for freshness has to have measured that agreement first.
+     */
+    updated: string;
+    /**
+     * The entry's `<rights>`, or `null` where it states none.
+     */
+    rights: string | null;
+    links: readonly AtomLink[];
+    /**
+     * The entry's `inspire_dls:spatial_dataset_identifier_code`, or `null` for a
+     * feed that is not an INSPIRE predefined-dataset feed.
+     */
+    identifierCode: string | null;
+}
+/**
+ * A feed's own links and its entries.
+ */
+export interface AtomFeed {
+    /**
+     * The feed's own links, which are the ones not inside an entry.
+     */
+    links: readonly AtomLink[];
+    entries: readonly AtomEntry[];
+}
+/**
+ * Read a feed's links and entries out of its markup.
+ *
+ * Streaming rather than whole-document, because a service document may be large:
+ * ČÚZK's lists one entry per municipality in 8,373,817 bytes, measured 2026-10-02.
+ *
+ * @param chunks The feed's bytes or text, in order.
+ * A Node `Readable` satisfies this.
+ * @throws When the markup is malformed, through the parser, so an unreadable feed raises
+ * rather than reading as a feed with fewer entries.
+ */
+export declare function readAtomFeed(chunks: AsyncIterable<string | Uint8Array>): Promise<AtomFeed>;
+/**
+ * The feed's text as the one chunk {@linkcode readAtomFeed} takes.
+ *
+ * For a caller that already holds the whole document, such as a test
+ * or a feed read through a buffering client.
+ */
+export declare function feedChunks(text: string): AsyncIterable<string>;
+/**
+ * The first link carrying `rel`, or `undefined` where the collection holds none.
+ *
+ * A feed's entry commonly carries several: ČÚZK writes a `describedby` link to its ISO 19139
+ * record beside the `alternate` link that is the data, and either would download as a dataset.
+ */
+export declare function linkWithRel(links: readonly AtomLink[], rel: string): AtomLink | undefined;
+//# sourceMappingURL=atom.d.ts.map

package/out/tools/fetch/atom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atom.d.ts","sourceRoot":"","sources":["../../../lib/tools/fetch/atom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;OAKG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC1B;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB;;OAEG;IACH,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC1B,OAAO,EAAE,SAAS,SAAS,EAAE,CAAA;CAC7B;AAyBD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,GAAG,UAAU,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAehG;AAED;;;;;GAKG;AACH,wBAAuB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAEzF"}

package/out/tools/fetch/atom.js

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Reads an INSPIRE predefined-dataset ATOM feed into its links and entries.
+ *
+ *   Several member states serve the Addresses (AD) theme as an ATOM feed rather than as a WFS, so
+ *   this is the shape a fetcher reads before it downloads anything. The elements are the same at
+ *   both levels of a two-level service: a service document's entry points at a dataset feed, and
+ *   that feed's entries point at files, and both are `<entry>` with `<link>` children.
+ *
+ *   Parsed with `@mailwoman/core/html/elements` rather than matched with a pattern, because a feed
+ *   needs the two things a pattern handles badly. An entry's open tag carries attributes
+ *   (`xml:lang`), and an href escapes the ampersand between its query parameters, so a reader has to
+ *   keep attributes and decode entities. XML mode is required: a feed's links self-close, and HTML
+ *   mode leaves them open.
+ *
+ *   Feed-level links are told from entry-level links by the parser rather than by position. Asking
+ *   for `link` and `entry` together yields a `link` only where it is not already inside an `entry`,
+ *   because capture runs to the outermost requested element's close.
+ */
+import { childElement, childElements, streamMarkupElements } from "@mailwoman/core/html/elements";
+function atomLinkOf(element) {
+    const length = element.attributes.length;
+    return {
+        href: element.attributes.href ?? "",
+        rel: (element.attributes.rel ?? "").toLowerCase(),
+        type: element.attributes.type ?? null,
+        title: element.attributes.title ?? null,
+        length: length !== undefined && /^\d+$/u.test(length) ? Number(length) : null,
+    };
+}
+function atomEntryOf(element) {
+    return {
+        id: childElement(element, "id")?.text ?? "",
+        title: childElement(element, "title")?.text ?? "",
+        updated: childElement(element, "updated")?.text ?? "",
+        rights: childElement(element, "rights")?.text ?? null,
+        links: childElements(element, "link").map(atomLinkOf),
+        identifierCode: childElement(element, "inspire_dls:spatial_dataset_identifier_code")?.text ?? null,
+    };
+}
+/**
+ * Read a feed's links and entries out of its markup.
+ *
+ * Streaming rather than whole-document, because a service document may be large:
+ * ČÚZK's lists one entry per municipality in 8,373,817 bytes, measured 2026-10-02.
+ *
+ * @param chunks The feed's bytes or text, in order.
+ * A Node `Readable` satisfies this.
+ * @throws When the markup is malformed, through the parser, so an unreadable feed raises
+ * rather than reading as a feed with fewer entries.
+ */
+export async function readAtomFeed(chunks) {
+    const links = [];
+    const entries = [];
+    for await (const element of streamMarkupElements(chunks, ["link", "entry"], { xml: true })) {
+        if (element.name === "entry") {
+            entries.push(atomEntryOf(element));
+            continue;
+        }
+        links.push(atomLinkOf(element));
+    }
+    return { links, entries };
+}
+/**
+ * The feed's text as the one chunk {@linkcode readAtomFeed} takes.
+ *
+ * For a caller that already holds the whole document, such as a test
+ * or a feed read through a buffering client.
+ */
+export async function* feedChunks(text) {
+    yield text;
+}
+/**
+ * The first link carrying `rel`, or `undefined` where the collection holds none.
+ *
+ * A feed's entry commonly carries several: ČÚZK writes a `describedby` link to its ISO 19139
+ * record beside the `alternate` link that is the data, and either would download as a dataset.
+ */
+export function linkWithRel(links, rel) {
+    return links.find((link) => link.rel === rel.toLowerCase());
+}
+//# sourceMappingURL=atom.js.map

package/out/tools/fetch/atom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atom.js","sourceRoot":"","sources":["../../../lib/tools/fetch/atom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAsB,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAwErH,SAAS,UAAU,CAAC,OAAsB;IACzC,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAA;IAExC,OAAO;QACN,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,IAAI,EAAE;QACnC,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE;QACjD,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,IAAI,IAAI;QACrC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI,IAAI;QACvC,MAAM,EAAE,MAAM,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;KAC7E,CAAA;AACF,CAAC;AAED,SAAS,WAAW,CAAC,OAAsB;IAC1C,OAAO;QACN,EAAE,EAAE,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,IAAI,EAAE;QAC3C,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,IAAI,EAAE;QACjD,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,IAAI,IAAI,EAAE;QACrD,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,IAAI,IAAI,IAAI;QACrD,KAAK,EAAE,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC;QACrD,cAAc,EAAE,YAAY,CAAC,OAAO,EAAE,6CAA6C,CAAC,EAAE,IAAI,IAAI,IAAI;KAClG,CAAA;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAA0C;IAC5E,MAAM,KAAK,GAAe,EAAE,CAAA;IAC5B,MAAM,OAAO,GAAgB,EAAE,CAAA;IAE/B,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,oBAAoB,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5F,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAA;YAElC,SAAQ;QACT,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAA;IAChC,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,UAAU,CAAC,IAAY;IAC7C,MAAM,IAAI,CAAA;AACX,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAA0B,EAAE,GAAW;IAClE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,GAAG,CAAC,WAAW,EAAE,CAAC,CAAA;AAC5D,CAAC"}

package/out/tools/fetch/cordis.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Download the CORDIS project archives for the `cordis` adapter.
+ *
+ * CORDIS serves one CSV archive per framework programme at
+ * `https://cordis.europa.eu/data/cordis-<programme>projects-csv.zip`, where the programme is `fp7`,
+ * `h2020` or `HORIZON` (Horizon Europe), the spelling the host serves. These are the distributions the
+ * data.europa.eu records `cordisfp7projects`, `cordish2020projects` and
+ * `cordis-eu-research-projects-under-horizon-europe-2021-2027` link. Each archive holds an
+ * `organization.csv` beside the project, topic and link tables, and the adapter reads that member
+ * straight out of the archive, so the archive is what this module keeps.
+ *
+ * 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/`.
+ *
+ * Measured on 2026-10-03, the host answers `HEAD` with `accept-ranges: bytes`, a `content-length`
+ * and a `last-modified` for each archive: `fp7` 32,953,397 bytes last modified `Thu, 02 Jan 2025
+ * 10:27:58 GMT`, `h2020` 55,219,250 bytes and `HORIZON` 36,908,998 bytes, both last modified on
+ * 22 September 2026. The re-run check compares that pair against the manifest, so a rerun makes
+ * one small request per archive, and an interrupted transfer resumes through
+ * {@linkcode resumableDownload}.
+ *
+ * A delivered archive is checked for its `organization.csv` member before the manifest records it,
+ * so an error page served under the archive's name never reaches the adapter.
+ */
+import { APIClient } from "@mailwoman/core/api";
+import { type PathBuilderLike } from "path-ts";
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download";
+/**
+ * The programmes CORDIS publishes an archive for, in the spelling the host serves.
+ */
+export declare const CORDIS_PROGRAMMES: readonly string[];
+/**
+ * The download URL for one programme's archive.
+ */
+export declare function cordisArchiveURL(programme: string): string;
+/**
+ * The file name one programme's archive is kept under, which is the URL's own last segment.
+ */
+export declare function cordisArchiveFilename(programme: string): string;
+/**
+ * The page whose license statement the adapter quotes.
+ */
+export declare const CORDIS_LEGAL_NOTICE_URL = "https://cordis.europa.eu/about/legal";
+/**
+ * What the manifest records per archive.
+ *
+ * {@linkcode SourceManifest}'s five fields describe the archive as it arrived.
+ * `last_modified` is what the re-run check compares before it downloads the body again.
+ */
+export interface CORDISArchiveManifest extends SourceManifest {
+    /**
+     * The `last-modified` the host served the archive under, or `null` where it served none.
+     */
+    last_modified: string | null;
+}
+/**
+ * What the host states about one archive without sending it.
+ */
+export interface CORDISArchiveHead {
+    lastModified: string | null;
+    contentLength: number | null;
+}
+/**
+ * Read what the host states about one archive.
+ *
+ * A header the host does not send is reported as `null` rather than raised on,
+ * and the caller then downloads rather than reading the absence as a match.
+ */
+export declare function readCORDISArchiveHead(client: Pick<APIClient, "fetch">, programme: string): Promise<CORDISArchiveHead>;
+/**
+ * Whether an archive on disk is still the one the manifest describes and the host still serves.
+ *
+ * The `HEAD` decides first, then the file's own length, then, when asked, its digest.
+ */
+export declare function isCORDISArchiveCurrent(recorded: CORDISArchiveManifest | undefined, head: CORDISArchiveHead, path: PathBuilderLike, verifyDigest: boolean): Promise<boolean>;
+export interface DownloadCORDISOptions {
+    /**
+     * Where the archives and the manifest are written.
+     * The directory itself is the adapter's `inputPath`.
+     */
+    outputDir: PathBuilderLike;
+    /**
+     * Which programmes to fetch.
+     * Defaults to {@linkcode CORDIS_PROGRAMMES}.
+     */
+    programmes?: readonly string[];
+    /**
+     * Re-read each archive's sha256 on a re-run instead of comparing its byte count.
+     */
+    verifyDigest?: boolean;
+    /**
+     * Download even where the `HEAD` agrees with the manifest.
+     */
+    force?: boolean;
+    /**
+     * Pause between range attempts, in milliseconds.
+     */
+    retryDelayMs?: number;
+    report?: (line: string) => void;
+}
+export type FetchCORDISOptions = BaseFetchOptions & Omit<DownloadCORDISOptions, "outputDir" | "report">;
+/**
+ * The directory `#adapters/cordis/adapter` reads under a fetch root.
+ */
+export declare function cordisInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike;
+/**
+ * Download each requested programme's archive into `options.outputDir` beside one manifest.
+ *
+ * Re-runnable per archive: one whose `HEAD` matches the manifest and whose file is
+ * still on disk at the recorded length makes no request for the body.
+ */
+export declare function downloadCORDIS(client: Pick<APIClient, "fetch">, options: DownloadCORDISOptions): Promise<FetchSummary>;
+/**
+ * Download the CORDIS archives into `<outRoot>/cordis/`.
+ *
+ * The registry entry point.
+ */
+export declare function fetchCORDIS(options: FetchCORDISOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=cordis.d.ts.map

package/out/tools/fetch/cordis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cordis.d.ts","sourceRoot":"","sources":["../../../lib/tools/fetch/cordis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAM/C,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAQ3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAA4B,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAGrH;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAgC,CAAA;AAE/E;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,yCAAyC,CAAA;AAO7E;;;;;GAKG;AACH,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC5D;;OAEG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAC1C,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,EAChC,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,iBAAiB,CAAC,CAS5B;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC3C,QAAQ,EAAE,qBAAqB,GAAG,SAAS,EAC3C,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,eAAe,EACrB,YAAY,EAAE,OAAO,GACnB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,SAAS,EAAE,eAAe,CAAA;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/B;AAED,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,GAAG,IAAI,CAAC,qBAAqB,EAAE,WAAW,GAAG,QAAQ,CAAC,CAAA;AAEvG;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,GAAG,eAAe,CAErF;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CACnC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,qBAAqB,GAC5B,OAAO,CAAC,YAAY,CAAC,CA8GvB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAYrH"}

package/out/tools/fetch/cordis.js

@@ -0,0 +1,208 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Download the CORDIS project archives for the `cordis` adapter.
+ *
+ * CORDIS serves one CSV archive per framework programme at
+ * `https://cordis.europa.eu/data/cordis-<programme>projects-csv.zip`, where the programme is `fp7`,
+ * `h2020` or `HORIZON` (Horizon Europe), the spelling the host serves. These are the distributions the
+ * data.europa.eu records `cordisfp7projects`, `cordish2020projects` and
+ * `cordis-eu-research-projects-under-horizon-europe-2021-2027` link. Each archive holds an
+ * `organization.csv` beside the project, topic and link tables, and the adapter reads that member
+ * straight out of the archive, so the archive is what this module keeps.
+ *
+ * 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/`.
+ *
+ * Measured on 2026-10-03, the host answers `HEAD` with `accept-ranges: bytes`, a `content-length`
+ * and a `last-modified` for each archive: `fp7` 32,953,397 bytes last modified `Thu, 02 Jan 2025
+ * 10:27:58 GMT`, `h2020` 55,219,250 bytes and `HORIZON` 36,908,998 bytes, both last modified on
+ * 22 September 2026. The re-run check compares that pair against the manifest, so a rerun makes
+ * one small request per archive, and an interrupted transfer resumes through
+ * {@linkcode resumableDownload}.
+ *
+ * A delivered archive is checked for its `organization.csv` member before the manifest records it,
+ * so an error page served under the archive's name never reaches the adapter.
+ */
+import { APIClient } from "@mailwoman/core/api";
+import { ByteFormatter } from "@mailwoman/core/fs/formatters";
+import { tryStat } from "@mailwoman/core/fs/readers";
+import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers";
+import { listZipEntries } from "@mailwoman/core/fs/zip";
+import { sha256File } from "@mailwoman/core/hash";
+import { PathBuilder } from "path-ts";
+import { CORDIS_ADAPTER_ID, CORDIS_ATTRIBUTION, CORDIS_LICENSE, CORDIS_ORGANIZATION_MEMBER, } from "#adapters/cordis/adapter";
+import { loadCollectionFiles, resumableDownload, writeManifest } from "#tools/fetch/download";
+/**
+ * The programmes CORDIS publishes an archive for, in the spelling the host serves.
+ */
+export const CORDIS_PROGRAMMES = ["fp7", "h2020", "HORIZON"];
+/**
+ * The download URL for one programme's archive.
+ */
+export function cordisArchiveURL(programme) {
+    return `https://cordis.europa.eu/data/cordis-${programme}projects-csv.zip`;
+}
+/**
+ * The file name one programme's archive is kept under, which is the URL's own last segment.
+ */
+export function cordisArchiveFilename(programme) {
+    return `cordis-${programme}projects-csv.zip`;
+}
+/**
+ * The page whose license statement the adapter quotes.
+ */
+export const CORDIS_LEGAL_NOTICE_URL = "https://cordis.europa.eu/about/legal";
+/**
+ * The directory the archives are written under, which is the adapter's `inputPath`.
+ */
+const SLUG = CORDIS_ADAPTER_ID;
+/**
+ * Read what the host states about one archive.
+ *
+ * A header the host does not send is reported as `null` rather than raised on,
+ * and the caller then downloads rather than reading the absence as a match.
+ */
+export async function readCORDISArchiveHead(client, programme) {
+    const response = await client.fetch({ method: "head", url: cordisArchiveURL(programme) });
+    const headers = response.headers;
+    const length = headers?.["content-length"];
+    return {
+        lastModified: headers?.["last-modified"] ?? null,
+        contentLength: length !== undefined && /^\d+$/u.test(length) ? Number(length) : null,
+    };
+}
+/**
+ * Whether an archive on disk is still the one the manifest describes and the host still serves.
+ *
+ * The `HEAD` decides first, then the file's own length, then, when asked, its digest.
+ */
+export async function isCORDISArchiveCurrent(recorded, head, path, verifyDigest) {
+    if (!recorded)
+        return false;
+    if (head.lastModified === null && head.contentLength === null)
+        return false;
+    if (head.lastModified !== null && head.lastModified !== recorded.last_modified)
+        return false;
+    if (head.contentLength !== null && head.contentLength !== recorded.bytes)
+        return false;
+    const stat = await tryStat(path);
+    if (!stat || stat.size !== recorded.bytes)
+        return false;
+    if (!verifyDigest)
+        return true;
+    return (await sha256File(path)) === recorded.sha256;
+}
+/**
+ * The directory `#adapters/cordis/adapter` reads under a fetch root.
+ */
+export function cordisInputPath(outRoot) {
+    return outRoot(SLUG);
+}
+/**
+ * Download each requested programme's archive into `options.outputDir` beside one manifest.
+ *
+ * Re-runnable per archive: one whose `HEAD` matches the manifest and whose file is
+ * still on disk at the recorded length makes no request for the body.
+ */
+export async function downloadCORDIS(client, options) {
+    const { report } = options;
+    const destDir = PathBuilder.from(options.outputDir);
+    const programmes = options.programmes?.length ? options.programmes : CORDIS_PROGRAMMES;
+    await makeDirectories(destDir);
+    const manifestPath = destDir("MANIFEST.json");
+    const recorded = (await loadCollectionFiles(manifestPath));
+    const written = new Map(recorded);
+    const summary = { fetched: 0, skipped: 0, failed: 0, failedCodes: [] };
+    report?.(`=== ${SLUG}`);
+    for (const programme of programmes) {
+        const filename = cordisArchiveFilename(programme);
+        const archivePath = destDir(filename);
+        const url = cordisArchiveURL(programme);
+        let head;
+        try {
+            head = await readCORDISArchiveHead(client, programme);
+        }
+        catch (error) {
+            report?.(`  ✗ ${programme}: ${error instanceof Error ? error.message : String(error)}`);
+            summary.failed++;
+            summary.failedCodes.push(programme);
+            continue;
+        }
+        report?.(`  ${programme}: ${head.contentLength === null ? "no content-length" : ByteFormatter.formatIEC(head.contentLength)}` +
+            `, last-modified ${head.lastModified ?? "absent"}`);
+        const current = !options.force &&
+            (await isCORDISArchiveCurrent(recorded.get(filename), head, archivePath, options.verifyDigest ?? false));
+        if (current) {
+            report?.(`  ✓ ${programme} already current — no download.`);
+            summary.skipped++;
+            continue;
+        }
+        let bytes;
+        try {
+            bytes = await resumableDownload({
+                url,
+                dest: archivePath,
+                headers: { accept: "application/zip, */*" },
+                retryDelayMs: options.retryDelayMs,
+                report,
+            });
+            const members = await listZipEntries(archivePath);
+            if (!members.some((member) => member.name === CORDIS_ORGANIZATION_MEMBER)) {
+                throw new Error(`the archive holds no ${CORDIS_ORGANIZATION_MEMBER}`);
+            }
+        }
+        catch (error) {
+            report?.(`  ✗ ${programme}: ${error instanceof Error ? error.message : String(error)}`);
+            await removePathIfPresent(archivePath);
+            summary.failed++;
+            summary.failedCodes.push(programme);
+            continue;
+        }
+        if (head.contentLength !== null && head.contentLength !== bytes) {
+            report?.(`  ! ${programme}: the HEAD stated ${head.contentLength} bytes and ${bytes} arrived, ` +
+                `so the archive was republished between the two requests`);
+        }
+        written.set(filename, {
+            source_url: url,
+            downloaded_at: new Date().toISOString(),
+            filename,
+            sha256: await sha256File(archivePath),
+            bytes,
+            last_modified: head.lastModified,
+        });
+        report?.(`  ✓ ${programme}: ${ByteFormatter.formatIEC(bytes)}`);
+        summary.fetched++;
+    }
+    const manifest = {
+        source: SLUG,
+        source_url: CORDIS_LEGAL_NOTICE_URL,
+        license: CORDIS_LICENSE,
+        attribution: CORDIS_ATTRIBUTION,
+        downloaded_at: new Date().toISOString(),
+        files: [...written.values()].toSorted((left, right) => left.filename.localeCompare(right.filename)),
+    };
+    await writeManifest(manifestPath, manifest);
+    report?.(`  MANIFEST written to ${manifestPath.toString()}`);
+    return summary;
+}
+/**
+ * Download the CORDIS archives into `<outRoot>/cordis/`.
+ *
+ * The registry entry point.
+ */
+export async function fetchCORDIS(options, report) {
+    await using client = new APIClient({ displayName: SLUG, retry: true });
+    // Awaited rather than returned: `await using` disposes the client when this scope exits.
+    return await downloadCORDIS(client, {
+        outputDir: options.outRoot(SLUG),
+        programmes: options.programmes,
+        verifyDigest: options.verifyDigest,
+        force: options.force,
+        retryDelayMs: options.retryDelayMs,
+        report,
+    });
+}
+//# sourceMappingURL=cordis.js.map

package/out/tools/fetch/cordis.js.map

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

package/out/tools/fetch/download/manifest.d.ts

@@ -4,24 +4,26 @@
  * @author Teffen Ellis, et al.
  * @file Reads and writes corpus-source manifests.
  */
+import type { PathBuilderLike } from "path-ts";
 import { type SourceManifest } from "#tools/fetch/download/network";
 /**
- * Read a MANIFEST.json; `null` when missing or corrupt (callers re-fetch from scratch).
+ * Read a manifest.json; `null` when missing or corrupt (callers re-fetch from scratch).
  */
-export declare function readManifest<T>(path: string): Promise<T | null>;
+export declare function readManifest<T>(path: PathBuilderLike): Promise<T | null>;
 /**
  * Load manifest entries into a map so untouched keys survive a partial re-fetch.
  */
-export declare function loadManifestEntries<T>(path: string, key: (entry: T) => string): Promise<Map<string, T>>;
+export declare function loadManifestEntries<T>(path: PathBuilderLike, key: (entry: T) => string): Promise<Map<string, T>>;
 /**
- * Write a MANIFEST.json in the house shape: pretty-printed, trailing newline.
+ * Write a manifest.json in the house shape: pretty-printed, trailing newline.
  */
-export declare function writeManifest(path: string, manifest: unknown): Promise<void>;
+export declare function writeManifest(path: PathBuilderLike, manifest: unknown): Promise<void>;
 /**
- * The sibling `MANIFEST.json` shape for a source that is a COLLECTION of files behind one portal (a monthly register
- * published per region, per industry, or per first letter). It carries what a trained artifact has to be able to cite
- * later: the license the portal labels the data with, the attribution wording it requires, and one
- * {@link SourceManifest} per file.
+ * The sibling `manifest.json` shape for a source that is a collection of files behind one
+ * portal (a monthly register published per region, per industry, or per first letter).
+ *
+ * It records what a trained artifact has to be able to cite later: the license the portal labels
+ * the data with, the attribution wording it requires and one {@link SourceManifest} per file.
  */
 export interface SourceCollectionManifest {
     source: string;
@@ -32,16 +34,23 @@ export interface SourceCollectionManifest {
     files: SourceManifest[];
 }
 /**
- * Pipe a response body to `dest` and answer the byte count. The one primitive the portal fetchers share when the
- * request is not a bare GET — a session cookie, a CSRF header, or a form POST stands between the listing and the file,
- * so {@link streamDownload}'s URL-only contract does not fit and each module builds its own `Response` first. Writes a
- * `.tmp` sibling and renames, so an interrupted transfer never lands at the final path looking complete.
+ * Pipe a response body to `dest` and answer the byte count.
+ *
+ * The one primitive the portal fetchers share when the request is not a bare GET.
+ * A session cookie, a csrf header, or a form post stands between the listing
+ * and the file, so {@link streamDownload}'s URL-only interface does not fit
+ * and each module builds its own `Response` first.
+ *
+ * Writes a `.tmp` sibling and renames, so an interrupted transfer never lands
+ * at the final path looking complete.
  */
-export declare function streamBodyToFile(res: Response, dest: string): Promise<number>;
+export declare function streamBodyToFile(res: Response, dest: PathBuilderLike): Promise<number>;
 /**
- * The per-file entries of a {@link SourceCollectionManifest} keyed by file name, or an empty map when the manifest is
- * missing or not in the collection shape, so a re-run after an interruption fetches only what is missing. The
- * single-file modules' `loadManifestEntries` reads a bare array and is not this.
+ * The per-file entries of a {@link SourceCollectionManifest} keyed by file name,
+ * or an empty map when the manifest is missing or not in the collection shape,
+ * so a re-run after an interruption fetches only what is missing.
+ *
+ * The single-file modules' `loadManifestEntries` reads a bare array and is not this.
  */
-export declare function loadCollectionFiles(path: string): Promise<Map<string, SourceManifest>>;
+export declare function loadCollectionFiles(path: PathBuilderLike): Promise<Map<string, SourceManifest>>;
 //# sourceMappingURL=manifest.d.ts.map

package/out/tools/fetch/download/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../../lib/tools/fetch/download/manifest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAEpF;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAQrE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAS7G;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,cAAc,EAAE,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBnF;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAS5F"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../../lib/tools/fetch/download/manifest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAEpF;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAQ9E;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAC1C,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GACvB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CASzB;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3F;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,cAAc,EAAE,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB5F;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CASrG"}