@mailwoman/corpus 10.0.0 → 10.1.0

package/out/it/adapters/anac/adapter.d.ts

@@ -0,0 +1,267 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `it-anac`: the OCDS release Autorità Nazionale Anticorruzione publishes for Italy's National
+ * Database of Public Contracts, read for the addresses of the public bodies named on each contract.
+ *
+ * Input is the publisher's own JSON Lines: one OCDS release per line, as
+ * `https://data.open-contracting.org/en/publication/117/download?name=<year>.jsonl.gz` serves it
+ * once decompressed. A release carries a `parties` array, and each party holds a `roles` list, a
+ * `name`, an `identifier` and an `address` whose four fields are `locality`, `postalCode`,
+ * `countryName` and `streetAddress`. The adapter streams the file through `JSONSpliterator`, so a
+ * year's release never sits in memory whole. `opts.inputPath` is one `.jsonl` edition or a directory
+ * holding several, which is what `fetchITANAC` writes.
+ *
+ * ## Which roles the adapter reads, and why those two
+ *
+ * The register's `addressRoles` for `it-procurement-grants-1` names exactly two fields,
+ * `parties[roles=buyer].address` and `parties[roles=payer].address`.
+ * Those two are the only address fields the release carries. Measured over the whole 2025 edition, 9,405 releases and
+ * 29,823 party objects in three roles: a `supplier` party holds no `address` key at all on 11,075 of
+ * 11,075, a `buyer` holds one on 9,381 of 9,381, and a `payer` on 9,359 of 9,367. So every address
+ * in this release belongs to a contracting authority or to the office that pays.
+ * Both of those are Italian public entities, and a contracting counterparty holds none.
+ *
+ * That is what makes this source admissible under the policy that a corpus carries the addresses of
+ * organizations and no address of an identifiable natural person. The two admitted roles are held by
+ * public bodies, and the one role whose parties can be sole traders publishes no address.
+ * {@linkcode readANACParty} still applies a name check and refuses a party whose name takes the
+ * `Surname, Firstname` form, because a later edition could carry one. On the 2025 edition the check
+ * refuses no party: 0 of the 18,740 address-bearing buyer and payer parties take that form, while 56
+ * hold a comma inside an organization name — `PARCO NAZIONALE DEL CILENTO, VALLO DI DIANO E
+ * ALBURNI` and `SETTORE PATRIMONIO, AMBIENTE E LAVORI PUBBLICI` among them — which is why the check
+ * requires a single word on each side of the comma rather than a comma alone.
+ *
+ * ## The street line
+ *
+ * Italy writes the house number after the street name and joins the two with a space, which is what
+ * `STREET_ORDERS` records as `number-last` and what `COMMA_JOINED_STREET_COUNTRIES` records by
+ * leaving `IT` out. {@linkcode splitTrailingStreetLine} performs the split. Three Italian
+ * conventions are normalized before it runs, each measured over the 2025 edition's 11,930
+ * non-placeholder street lines:
+ *
+ * 1. **A trailing copy of the locality.** 406 lines end with the value the publisher writes in its
+ *    own `locality` field — `CORSO ITALIA, 29 FIRENZE` against `locality` `FIRENZE`. The copy is
+ *    removed only where it equals that field, so the publisher's own record is what authorizes the
+ *    removal rather than a place-name list.
+ * 2. **A civic marker.** 1,222 lines write `numero civico` as a marker before the number, spaced as
+ *    `PIAZZA ROOSEVELT N 1` or glued as `VIA ROMA N.68`. The marker is dropped, so the street is
+ *    `PIAZZA ROOSEVELT` rather than `PIAZZA ROOSEVELT N`.
+ * 3. **`senza numero`.** 182 lines end `SNC` or `SN`, which states that the premise has no civic
+ *    number, so the tail is dropped and no `house_number` is composed from it.
+ *
+ * A kilometer point is not a house number. `S.S. 7 APPIA KM 671` names a point on a state highway,
+ * so a number preceded by `KM` is left in the street line, which then refuses the row under the rule
+ * below.
+ *
+ * **A street line holding a digit the split could not place refuses the row.**
+ * {@linkcode ANACRefusal.StreetNumberUnplaced} covers 194 of those 11,930 lines, where the publisher
+ * appends a qualifier after the number: `VIA CIRCONVALLAZIONE, 1 PARCO IDROSCALO`, `VIA FELTRE 57
+ * 32100 BELLUNO (BL)`, `VIA SAN SECONDO 29 BIS`. Emitting them would label a civic number as part of
+ * a street name. A line with no digit at all is emitted as a street with no number, which is the
+ * ordinary `PIAZZA CASTELLO` case and 1,416 of the 11,930. The remaining 10,320 carry a number.
+ *
+ * Two limits of the split are the publisher's own ambiguity rather than this reader's. `PIAZZA
+ * UMBERTO 1` is Umberto I's square and reads identically to civic number 1, and the release gives no
+ * field that separates them. A number written twice, as `CORSO ITALIA 55 55` and `VIALE DEI PIANETI 1
+ * 1`, leaves the first copy in the street name. Together with Italy's date-named streets — `VIA 4
+ * NOVEMBRE`, `PIAZZA 1 MAGGIO`, `VIA 2 AGOSTO 1980` — 93 of the 10,320 numbered lines keep a digit
+ * inside the street, and most of those digits belong to the street's name.
+ *
+ * ## What the split was checked against
+ *
+ * The release publishes no preformatted address line, so no field of the publisher's states the
+ * written form this adapter composes. The check available is reversibility against the publisher's
+ * own string: the composed `street` and `house_number`, rejoined, reproduce the published
+ * `streetAddress` on 11,736 of the 11,736 street lines this adapter emits, after the three
+ * normalizations above and folding case, inner whitespace and the comma. Against the published
+ * string as published, 10,027 of 11,736 reproduce it exactly under the same folding, and each of the
+ * 1,709 that do not differs by one of those three normalizations. The split therefore loses no
+ * published token. Which side of the split each token belongs on is the part no field of this
+ * publisher's confirms.
+ *
+ * Every other component is a published value copied unchanged, which the same pass checked: 0 of the
+ * 18,473 rows the 2025 edition admits carry a `locality`, `postcode` or `venue` that differs from the
+ * field it came from.
+ *
+ * ## Placeholders and the postcode
+ *
+ * The publisher writes the literal `N.A.` where it holds no value: 476 postcodes, 6 localities and 6
+ * street lines on the 2025 edition. {@linkcode isPlaceholderValue} treats it as absent, so no row
+ * carries `N.A.` as a postcode.
+ *
+ * An Italian CAP is five digits. A postcode that is neither a placeholder nor five digits is not a
+ * CAP, and the row is refused rather than stripped of the field: the one such value on the 2025
+ * edition is `01238-000`, a São Paulo CEP on the payer `ISTITUTO ITALIANO DI CULTURA DI SAN PAOLO`,
+ * whose address is in Brazil rather than Italy. A `countryName` naming any country but Italy refuses
+ * the row for the same reason. Buyers write `ITALY` on all 9,381 rows and payers write no
+ * `countryName` at all.
+ *
+ * ## Identity and license
+ *
+ * The row id is content-addressed over the aligned components. The publisher's party identifier
+ * cannot serve: a buyer's `IT-CF` fiscal code carries more than one address on 17 of 3,119 distinct
+ * codes, and one address recurs across hundreds of releases, so the identifier identifies the
+ * organization rather than the address.
+ *
+ * The OCP Data Registry publishes this release under CC BY 4.0, which the address-source register
+ * elected on 2026-09-30 with `spdx` `CC-BY-4.0`. CC BY requires credit, a link to the license and a
+ * statement that changes were made, so every row records the license and
+ * {@linkcode IT_ANAC_ATTRIBUTION} is the credit the model card carries.
+ *
+ * The adapter honors `opts.limit`, `opts.signal` and `opts.country`.
+ */
+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 IT_ANAC_ADAPTER_ID = "it-anac";
+/**
+ * The one jurisdiction this adapter emits.
+ *
+ * ANAC's release covers Italian public contracting, so the set has one member.
+ */
+export declare const IT_ANAC_COUNTRIES: readonly string[];
+/**
+ * The license the address-source register elected for this publication.
+ *
+ * The OCP Data Registry's publication page for id 117 states Creative Commons Attribution
+ * 4.0 International, and the register records it under `spdx` as `CC-BY-4.0`.
+ */
+export declare const IT_ANAC_LICENSE = "CC-BY-4.0";
+/**
+ * The credit CC BY 4.0 obliges, which the model card carries beside the license
+ * and a statement that the data was changed.
+ */
+export declare const IT_ANAC_ATTRIBUTION = "Autorit\u00E0 Nazionale Anticorruzione (ANAC), via the OCP Data Registry";
+/**
+ * The two party roles the adapter reads.
+ *
+ * The register's `addressRoles` names these two fields alone.
+ * The `supplier` role is the one role whose parties are contracting counterparties
+ * rather than public bodies.
+ * That role publishes no `address` object.
+ */
+export declare const IT_ANAC_PARTY_ROLES: readonly string[];
+/**
+ * Why a party's address did not become a row.
+ *
+ * The reading returns one of these rather than an empty result, so a caller counting
+ * refusals knows which condition each party met.
+ * `tools/dev-tools` and the adapter's test both count them.
+ */
+export declare const ANACRefusal: {
+    /**
+     * The party holds a role other than `buyer` or `payer`, so its address is out
+     * of scope even where it carries one.
+     */
+    readonly RoleNotAdmitted: "role-not-admitted";
+    /**
+     * The party carries no `address` object, or every field in it is empty or a placeholder.
+     */
+    readonly AddressAbsent: "address-absent";
+    /**
+     * The address states no locality, so no component places it.
+     */
+    readonly LocalityAbsent: "locality-absent";
+    /**
+     * The street line holds a digit that the split could not read as a house number.
+     */
+    readonly StreetNumberUnplaced: "street-number-unplaced";
+    /**
+     * The postcode is neither absent nor a five-digit Italian CAP.
+     */
+    readonly PostcodeNotCAP: "postcode-not-cap";
+    /**
+     * `countryName` names a country other than Italy.
+     */
+    readonly CountryNotItaly: "country-not-italy";
+    /**
+     * The party name takes the `Surname, Firstname` form a natural person's name takes.
+     */
+    readonly NamePersonalForm: "name-personal-form";
+    /**
+     * The components the party yielded do not render as an Italian address line.
+     */
+    readonly Unrenderable: "unrenderable";
+    /**
+     * The rendered line carries one component, so it is a place name rather than an address.
+     *
+     * A party whose name holds no letter, whose postcode is the publisher's placeholder
+     * and whose street line is absent leaves the locality alone.
+     */
+    readonly ComponentsTooFew: "components-too-few";
+};
+/**
+ * One of the {@link ANACRefusal} reasons.
+ */
+export type ANACRefusal = (typeof ANACRefusal)[keyof typeof ANACRefusal];
+/**
+ * What one party yielded: a row, or the reason it yielded none.
+ */
+export type ANACPartyReading = {
+    readonly admitted: CanonicalRow;
+} | {
+    readonly refused: ANACRefusal;
+};
+/**
+ * The OCDS address object, carrying the four fields this release populates.
+ */
+export interface ANACAddress {
+    locality?: string | null;
+    postalCode?: string | null;
+    countryName?: string | null;
+    streetAddress?: string | null;
+}
+/**
+ * One `parties` member of a release.
+ */
+export interface ANACParty {
+    name?: string | null;
+    roles?: readonly string[] | null;
+    address?: ANACAddress | null;
+}
+/**
+ * One line of the input: an OCDS release.
+ *
+ * The adapter reads `parties` alone.
+ * A release also carries `tender`, `awards` and `contracts`, and no address
+ * sits on any of them in this publication.
+ */
+export interface ANACRelease {
+    ocid?: string;
+    parties?: readonly ANACParty[] | null;
+}
+/**
+ * Whether a published value is the publisher's placeholder for an absent one,
+ * or holds no letter and no digit at all.
+ *
+ * A placeholder read at face value would reach a corpus as a postcode spelled `N.A.`.
+ */
+export declare function isPlaceholderValue(value: string): boolean;
+/**
+ * The street line with the three Italian conventions normalized away: a trailing copy
+ * of the locality, a civic marker before the number, and a `senza numero` tail.
+ *
+ * `locality` is the publisher's own value for this party, which is what
+ * authorizes removing the trailing copy.
+ * An empty string leaves the line as it is.
+ */
+export declare function normalizeANACStreetLine(line: string, locality: string): string;
+/**
+ * Read one party's address into a row, or report why it yielded none.
+ *
+ * Exported because the refusal reasons are the measurement this adapter is checked by: a caller reading
+ * a whole edition counts them per reason rather than observing a row count it cannot account for.
+ */
+export declare function readANACParty(party: ANACParty): ANACPartyReading;
+export declare function createITANACAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const itANACAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/it/adapters/anac/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../lib/it/adapters/anac/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAWH,OAAO,EAAoC,KAAK,YAAY,EAAE,KAAK,aAAa,EAAiB,MAAM,QAAQ,CAAA;AAE/G;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAE3C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAW,CAAA;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,eAAe,cAAc,CAAA;AAE1C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,6EAAwE,CAAA;AAExG;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAuB,CAAA;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;IACvB;;;OAGG;aACH,eAAe,EAAE,mBAAmB;IACpC;;OAEG;aACH,aAAa,EAAE,gBAAgB;IAC/B;;OAEG;aACH,cAAc,EAAE,iBAAiB;IACjC;;OAEG;aACH,oBAAoB,EAAE,wBAAwB;IAC9C;;OAEG;aACH,cAAc,EAAE,kBAAkB;IAClC;;OAEG;aACH,eAAe,EAAE,mBAAmB;IACpC;;OAEG;aACH,gBAAgB,EAAE,oBAAoB;IACtC;;OAEG;aACH,YAAY,EAAE,cAAc;IAC5B;;;;;OAKG;aACH,gBAAgB,EAAE,oBAAoB;CAC7B,CAAA;AAEV;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAA;AAExE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAA;AAEtG;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IAChC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CAAA;CACrC;AAwDD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQzD;AAWD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU9E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,gBAAgB,CAsFhE;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CA0CnD;AA2BD;;GAEG;AACH,eAAO,MAAM,aAAa,eAAwB,CAAA"}