euredact 0.3.0 → 0.3.2

package/dist/cjs/sdk.js

@@ -4,6 +4,7 @@ exports.EuRedact = void 0;
 const cache_js_1 = require("./cache.js");
 const normalizer_js_1 = require("./normalizer.js");
 const engine_js_1 = require("./rules/engine.js");
+const evidence_js_1 = require("./rules/evidence.js");
 const types_js_1 = require("./types.js");
 const DATE_TYPES = new Set([types_js_1.EntityType.DOB, types_js_1.EntityType.DATE_OF_DEATH]);
 class ReferentialMapper {
@@ -47,12 +48,18 @@ class EuRedact {
                 `(${this.maxInputLength.toLocaleString()} chars). Split the input or ` +
                 `increase maxInputLength when constructing EuRedact.`);
         }
-        const { countries = null, mode = "rules", referentialIntegrity = false, detectDates = false, cache = true, } = options;
+        const { countries = null, countryHint = null, context = null, chunkOffset = 0, mode = "rules", referentialIntegrity = false, detectDates = false, } = options;
+        // A context makes the result depend on evidence from other chunks, so the
+        // text no longer identifies the result. Caching is disabled rather than
+        // keyed on the context, whose contents change as chunks arrive.
+        const cache = context !== null ? false : (options.cache ?? true);
         const [normalizedText, offsetMapping] = (0, normalizer_js_1.normalize)(text);
         const countriesTuple = countries
             ? countries.map(c => c.toUpperCase()).sort()
             : ["ALL"];
-        const cacheMode = `${mode}|dates=${detectDates}`;
+        // countryHint changes attribution, so it must key the cache too.
+        const hintKey = countryHint ? countryHint.map(c => c.toUpperCase()).sort().join(",") : "";
+        const cacheMode = `${mode}|dates=${detectDates}|hint=${hintKey}`;
         let cacheKey;
         if (cache) {
             cacheKey = this.cache.key(normalizedText, countriesTuple, cacheMode);
@@ -60,7 +67,10 @@ class EuRedact {
             if (cached !== null)
                 return cached;
         }
-        let detections = this.engine.detect(normalizedText, countries);
+        const { detections: rawDetections, evidence, scores, } = this.engine.detectWithEvidence(normalizedText, countries, countryHint, context !== null ? context.evidence() : null);
+        if (context !== null)
+            context.add(evidence, chunkOffset);
+        let detections = rawDetections;
         if (offsetMapping !== null) {
             detections = detections.map(d => ({
                 ...d,
@@ -80,11 +90,18 @@ class EuRedact {
                 : `[${det.entityType}]`;
             redacted = redacted.slice(0, det.start) + replacement + redacted.slice(det.end);
         }
+        // Report the inference so it can be audited. Spans in `evidence` are
+        // offsets into the normalised text, matching `detections`.
+        const inferredCountries = [...(0, evidence_js_1.weightsToRanking)(scores).entries()]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
         const result = {
             redactedText: redacted,
             detections,
             source: "rules",
             degraded: false,
+            inferredCountries,
+            evidence,
+            detectionMode: countries && countries.length ? "declared" : "inferred",
         };
         if (cache && cacheKey) {
             this.cache.put(cacheKey, result);
@@ -92,8 +109,9 @@ class EuRedact {
         return result;
     }
     redactBatch(texts, options = {}) {
-        const countries = options.countries ?? null;
-        this.engine.loadCountries(countries ? countries.map(c => c.toUpperCase()) : null);
+        // Generation is country-blind, so every country's patterns are loaded
+        // regardless of what the caller declared.
+        this.engine.loadCountries(null);
         return texts.map(text => this.redact(text, options));
     }
 }

package/dist/esm/index.d.ts

@@ -1,5 +1,6 @@
 export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES } from "./types.js";
-export type { Detection, RedactResult, PatternDef, CountryConfig } from "./types.js";
+export type { Detection, RedactResult, PatternDef, CountryConfig, CountryEvidence } from "./types.js";
+export { DocumentContext } from "./rules/context.js";
 export { EuRedact, type RedactOptions } from "./sdk.js";
 export { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 export { setBicRegistry, getBicRegistry, SEED_BIC6_PREFIXES, type BicRegistryProvider } from "./rules/bicRegistry.js";

package/dist/esm/index.js

@@ -1,4 +1,5 @@
 export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES } from "./types.js";
+export { DocumentContext } from "./rules/context.js";
 export { EuRedact } from "./sdk.js";
 export { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 export { setBicRegistry, getBicRegistry, SEED_BIC6_PREFIXES } from "./rules/bicRegistry.js";

package/dist/esm/rules/context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Country evidence shared across the chunks of one document.
+ *
+ * A long document is usually redacted in pieces. Each piece is scanned
+ * independently, so each infers its own country — and a chunk that happens to
+ * contain no IBAN, no `+CC` number and no ccTLD infers nothing at all, even
+ * when the first page identified the document beyond doubt:
+ *
+ *     page 1   "Factuur — IBAN NL91ABNA0417164300, info@jansen.nl"
+ *     page 7   "Telefoon 0612345678"        <- Dutch mobile, or Danish CPR?
+ *
+ * Scanned alone, page 7 has nothing to go on. Sharing a context across the two
+ * carries page 1's evidence forward, and the number resolves as a Dutch phone.
+ *
+ * Spans are rebased by `chunkOffset` on the way in, so evidence collected from
+ * a chunk points at offsets in the whole document rather than the chunk.
+ *
+ * A context influences **scoring only**. It can change which national scheme is
+ * attributed to a value. It can never change which spans are found, so a
+ * context carried over from the wrong document cannot cause a miss.
+ */
+import type { CountryEvidence } from "../types.js";
+export declare class DocumentContext {
+    private seen;
+    private items;
+    /** Record evidence from a chunk starting at `chunkOffset`. */
+    add(evidence: CountryEvidence[], chunkOffset?: number): void;
+    /** Everything recorded so far, spans rebased to the whole document. */
+    evidence(): CountryEvidence[];
+    get size(): number;
+}

package/dist/esm/rules/context.js

@@ -0,0 +1,46 @@
+/**
+ * Country evidence shared across the chunks of one document.
+ *
+ * A long document is usually redacted in pieces. Each piece is scanned
+ * independently, so each infers its own country — and a chunk that happens to
+ * contain no IBAN, no `+CC` number and no ccTLD infers nothing at all, even
+ * when the first page identified the document beyond doubt:
+ *
+ *     page 1   "Factuur — IBAN NL91ABNA0417164300, info@jansen.nl"
+ *     page 7   "Telefoon 0612345678"        <- Dutch mobile, or Danish CPR?
+ *
+ * Scanned alone, page 7 has nothing to go on. Sharing a context across the two
+ * carries page 1's evidence forward, and the number resolves as a Dutch phone.
+ *
+ * Spans are rebased by `chunkOffset` on the way in, so evidence collected from
+ * a chunk points at offsets in the whole document rather than the chunk.
+ *
+ * A context influences **scoring only**. It can change which national scheme is
+ * attributed to a value. It can never change which spans are found, so a
+ * context carried over from the wrong document cannot cause a miss.
+ */
+export class DocumentContext {
+    // Deduped on the same key evidence.collect() uses, so re-running a chunk — a
+    // retry, an overlapping window — cannot let one entity vote twice and
+    // outweigh the rest of the document.
+    seen = new Set();
+    items = [];
+    /** Record evidence from a chunk starting at `chunkOffset`. */
+    add(evidence, chunkOffset = 0) {
+        for (const ev of evidence) {
+            const span = [ev.span[0] + chunkOffset, ev.span[1] + chunkOffset];
+            const key = `${span[0]}:${span[1]}:${ev.source}`;
+            if (this.seen.has(key))
+                continue;
+            this.seen.add(key);
+            this.items.push(chunkOffset === 0 ? ev : { ...ev, span });
+        }
+    }
+    /** Everything recorded so far, spans rebased to the whole document. */
+    evidence() {
+        return [...this.items];
+    }
+    get size() {
+        return this.items.length;
+    }
+}

package/dist/esm/rules/countries/index.js

@@ -214,7 +214,13 @@ const DE = {
         p(EntityType.PHONE, String.raw `\b0[1-9]\d{1,4}[\s/\-]?\d{3,8}\b`),
         p(EntityType.PHONE, String.raw `\+49\s?\d{2,5}[\s/\-]?\d{3,8}\b`),
         p(EntityType.PASSPORT, String.raw `\b[CFGHJK][0-9A-Z]{8,9}\b`, null, "", ["Reisepass", "passport", "Passnummer", "Reisepassnummer", "Reisepass Nummer", "Reisepass-Nr", "Pass Nr"], true),
-        p(EntityType.LICENSE_PLATE, String.raw `\b[A-ZÄÖÜ]{1,3}[\s\-]?[A-Z]{1,2}[\s\-]?\d{1,4}[EH]?\b`),
+        // The separator after the city code is mandatory. When it was optional, a
+        // contiguous letter run split across both groups and the hyphen was
+        // consumed as the *second* separator, so any "LETTERS-DIGITS" token
+        // matched: ICD-10 parsed as city "IC" + letters "D" + "-" + "10", and
+        // ISO-9001, COVID-19, RFC-2822, POL-2025 likewise. A real plate always
+        // separates the city code: "B-AB 1234", "M-XY 99".
+        p(EntityType.LICENSE_PLATE, String.raw `\b[A-ZÄÖÜ]{1,3}[\s\-][A-Z]{1,2}[\s\-]?\d{1,4}[EH]?\b`),
         p(EntityType.POSTAL_CODE, String.raw `\b\d{5}\b`, null, "", ["PLZ", "Postleitzahl", "postal code", "postcode", "Anschrift", "Adresse", "Wohnort", "Ort", "Stadt", "wohnt", "wohnhaft", "Straße", "Str.", "Weg", "Platz", "Allee", "Ring"], true),
         p(EntityType.CHAMBER_OF_COMMERCE, String.raw `\bHR[AB]\s?\d{4,6}\b`),
         p(EntityType.SSN, String.raw `\b\d{2}[\s]?\d{6}[\s]?[A-Z][\s]?\d{3}\b`, null, "", ["Rentenversicherung", "RV-Nummer", "Sozialversicherung", "SV-Nummer", "Versicherungsnummer", "Rentenversicherungsnummer", "Sozialversicherungsnummer"], true),

package/dist/esm/rules/deDistricts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * German vehicle registration district codes (Unterscheidungszeichen).
+ *
+ * The set is closed: codes are fixed by the Fahrzeug-Zulassungsverordnung and
+ * maintained by the Kraftfahrt-Bundesamt, changing only when a district is
+ * created, merged, or a historic code is reinstated. That makes membership a
+ * usable precision signal — unlike the open-ended blocklist of standards
+ * prefixes it replaces, which only ever catches acronyms someone thought of.
+ *
+ * Used as a **tier**, not a filter: code on this list -> emit; code absent but
+ * a plate cue nearby -> emit; neither -> reject. So a missing code costs
+ * recall only where there is also no cue. Some entries are also standards
+ * prefixes — DIN is Dinslaken as well as the standards body — which is why the
+ * standards guard is kept alongside this one.
+ */
+export declare const DE_DISTRICT_CODES: ReadonlySet<string>;

package/dist/esm/rules/deDistricts.js

@@ -0,0 +1,89 @@
+/**
+ * German vehicle registration district codes (Unterscheidungszeichen).
+ *
+ * The set is closed: codes are fixed by the Fahrzeug-Zulassungsverordnung and
+ * maintained by the Kraftfahrt-Bundesamt, changing only when a district is
+ * created, merged, or a historic code is reinstated. That makes membership a
+ * usable precision signal — unlike the open-ended blocklist of standards
+ * prefixes it replaces, which only ever catches acronyms someone thought of.
+ *
+ * Used as a **tier**, not a filter: code on this list -> emit; code absent but
+ * a plate cue nearby -> emit; neither -> reject. So a missing code costs
+ * recall only where there is also no cue. Some entries are also standards
+ * prefixes — DIN is Dinslaken as well as the standards body — which is why the
+ * standards guard is kept alongside this one.
+ */
+export const DE_DISTRICT_CODES = new Set([
+    "A", "AA", "AB", "ABG", "AC", "AE", "AH", "AIB", "AIC", "AK", "AL", "ALF",
+    "ALS", "ALZ", "AM", "AN", "ANA", "ANG", "ANK", "AP", "APD", "AR", "ARN",
+    "ART", "AS", "ASD", "ASL", "ASZ", "AT", "AU", "AUR", "AW", "AZ", "AZE",
+    "AÖ", "B", "BA", "BAD", "BAR", "BB", "BBG", "BBL", "BC", "BCH", "BD",
+    "BE", "BED", "BEI", "BEL", "BER", "BF", "BG", "BGD", "BGL", "BH", "BI",
+    "BID", "BIN", "BIR", "BIT", "BIW", "BK", "BKS", "BL", "BLB", "BLK", "BM",
+    "BN", "BNA", "BO", "BOG", "BOH", "BOR", "BOT", "BP", "BR", "BRA", "BRB",
+    "BRG", "BRI", "BRK", "BRL", "BRV", "BS", "BSB", "BSK", "BT", "BTF", "BU",
+    "BUL", "BUR", "BW", "BWL", "BYL", "BZ", "BZA", "BÖ", "BÜD", "BÜS", "BÜZ",
+    "C", "CA", "CAS", "CB", "CE", "CHA", "CHL", "CLP", "CLZ", "CO", "COC",
+    "COE", "CR", "CT", "CUX", "CW", "D", "DA", "DAH", "DAN", "DAU", "DB",
+    "DBR", "DD", "DE", "DEG", "DEL", "DG", "DGF", "DH", "DI", "DIL", "DIN",
+    "DIZ", "DKB", "DL", "DLG", "DM", "DN", "DO", "DON", "DS", "DT", "DU",
+    "DUD", "DW", "DZ", "DÜW", "E", "EA", "EB", "EBE", "EBN", "EBS", "ECK",
+    "ED", "EE", "EF", "EG", "EH", "EHI", "EI", "EIC", "EIH", "EIL", "EIN",
+    "EIS", "EL", "EM", "EMD", "EMS", "EN", "ER", "ERB", "ERH", "ERK", "ES",
+    "ESA", "ESB", "ESW", "EU", "EUT", "EW", "F", "FAL", "FB", "FD", "FDB",
+    "FDS", "FEU", "FF", "FFB", "FG", "FH", "FI", "FKB", "FL", "FLÖ", "FN",
+    "FO", "FOR", "FR", "FRG", "FRI", "FRW", "FS", "FT", "FTL", "FW", "FZ",
+    "FÜ", "FÜS", "G", "GA", "GAN", "GAP", "GC", "GD", "GDB", "GE", "GEL",
+    "GEM", "GEO", "GER", "GF", "GG", "GHA", "GHC", "GI", "GK", "GL", "GLA",
+    "GM", "GMN", "GN", "GNT", "GOA", "GOH", "GP", "GR", "GRA", "GRH", "GRI",
+    "GRM", "GRS", "GRZ", "GS", "GT", "GTH", "GUB", "GUN", "GV", "GVM", "GW",
+    "GZ", "GÖ", "GÜ", "H", "HA", "HAB", "HAL", "HAM", "HAS", "HB", "HBN",
+    "HBS", "HC", "HCH", "HD", "HDH", "HDL", "HE", "HEB", "HEF", "HEI", "HEL",
+    "HER", "HET", "HF", "HG", "HGN", "HGW", "HH", "HHM", "HI", "HIG", "HIP",
+    "HK", "HL", "HM", "HMU", "HN", "HO", "HOG", "HOH", "HOL", "HOM", "HOR",
+    "HOT", "HP", "HR", "HRO", "HS", "HSK", "HST", "HU", "HUS", "HV", "HVL",
+    "HW", "HWI", "HX", "HY", "HZ", "HÖS", "HÜN", "IGB", "IK", "IL", "ILL",
+    "IN", "IS", "IZ", "J", "JB", "JE", "JEV", "JL", "JÜL", "K", "KA", "KAR",
+    "KB", "KC", "KE", "KEH", "KEL", "KEM", "KF", "KG", "KH", "KI", "KIB",
+    "KK", "KL", "KLE", "KLT", "KLZ", "KM", "KN", "KO", "KOZ", "KR", "KRU",
+    "KS", "KT", "KU", "KUS", "KW", "KY", "KYF", "KÖN", "KÖT", "KÜN", "L",
+    "LA", "LAN", "LAT", "LAU", "LB", "LBS", "LBZ", "LC", "LD", "LDK", "LDS",
+    "LE", "LEO", "LER", "LEV", "LF", "LG", "LH", "LI", "LIB", "LIF", "LIN",
+    "LIP", "LK", "LL", "LM", "LN", "LOH", "LOS", "LP", "LR", "LS", "LSA",
+    "LSN", "LSZ", "LU", "LUK", "LWL", "LÖ", "LÖB", "LÜD", "LÜN", "M", "MA",
+    "MAB", "MAI", "MAK", "MAL", "MAR", "MB", "MC", "MD", "ME", "MED", "MEG",
+    "MEI", "MEK", "MEL", "MEP", "MER", "MES", "MET", "MG", "MGH", "MGN", "MH",
+    "MHL", "MI", "MIL", "MK", "MKK", "ML", "MM", "MN", "MO", "MOD", "MOL",
+    "MON", "MOS", "MQ", "MR", "MS", "MSP", "MST", "MT", "MTK", "MTL", "MVL",
+    "MW", "MY", "MYK", "MZ", "MZG", "MÜ", "MÜB", "MÜL", "MÜN", "MÜR", "N",
+    "NAB", "NAI", "NAU", "NB", "ND", "NDH", "NE", "NEA", "NEB", "NEC", "NEN",
+    "NES", "NEU", "NEW", "NF", "NH", "NI", "NIB", "NK", "NL", "NM", "NMB",
+    "NMS", "NOH", "NOL", "NOM", "NOR", "NP", "NR", "NRW", "NRÜ", "NT", "NU",
+    "NVP", "NW", "NWM", "NY", "NZ", "NÖ", "OA", "OAL", "OB", "OBB", "OBG",
+    "OC", "OCH", "OD", "OE", "OF", "OG", "OH", "OHA", "OHV", "OHZ", "OK",
+    "OL", "OLD", "OP", "OPR", "OR", "OS", "OSL", "OTT", "OTW", "OVI", "OVL",
+    "OVP", "OZ", "P", "PA", "PAF", "PAN", "PAR", "PB", "PCH", "PE", "PEG",
+    "PER", "PF", "PI", "PIR", "PK", "PL", "PLÖ", "PM", "PN", "PR", "PRÜ",
+    "PS", "PW", "PZ", "QFT", "QLB", "R", "RA", "RC", "RD", "RDG", "RE", "REG",
+    "REH", "REI", "RG", "RH", "RI", "RID", "RIE", "RL", "RM", "RN", "RO",
+    "ROD", "ROF", "ROH", "ROK", "ROL", "ROS", "ROT", "ROW", "RPL", "RS",
+    "RSL", "RT", "RU", "RV", "RW", "RWL", "RY", "RZ", "RÜD", "RÜG", "S", "SA",
+    "SAB", "SAD", "SAL", "SAN", "SAO", "SAW", "SB", "SBG", "SBK", "SC", "SCZ",
+    "SDH", "SDL", "SDT", "SE", "SEB", "SEE", "SEF", "SEL", "SF", "SFA", "SFB",
+    "SFT", "SG", "SGH", "SH", "SHA", "SHG", "SHK", "SHL", "SHS", "SI", "SIG",
+    "SIM", "SK", "SL", "SLE", "SLF", "SLG", "SLK", "SLN", "SLS", "SLZ", "SLÜ",
+    "SM", "SMÜ", "SN", "SNH", "SO", "SOB", "SOG", "SOK", "SOL", "SON", "SP",
+    "SPB", "SPN", "SPR", "SR", "SRB", "SRO", "ST", "STA", "STB", "STD", "STE",
+    "STH", "STL", "STO", "SU", "SUL", "SW", "SWA", "SWZ", "SY", "SZ", "SZB",
+    "SÄK", "SÖM", "SÜW", "TBB", "TE", "TF", "TG", "TGO", "THL", "THW", "TIR",
+    "TO", "TP", "TR", "TS", "TT", "TUT", "TÖL", "TÖN", "TÜ", "UE", "UEM",
+    "UER", "UFF", "UH", "UL", "UM", "UN", "USI", "V", "VAI", "VB", "VEC",
+    "VER", "VIB", "VIE", "VIT", "VK", "VL", "VOF", "VOH", "VR", "VS", "W",
+    "WA", "WAF", "WAK", "WAM", "WAN", "WAR", "WAT", "WB", "WBS", "WD", "WDA",
+    "WE", "WEB", "WEG", "WEI", "WEL", "WEM", "WEN", "WER", "WES", "WF", "WG",
+    "WHV", "WI", "WIL", "WIS", "WIT", "WIZ", "WK", "WL", "WLG", "WM", "WMS",
+    "WN", "WND", "WO", "WOB", "WOH", "WOL", "WOR", "WOS", "WR", "WRN", "WS",
+    "WSF", "WST", "WSW", "WT", "WTL", "WTM", "WUG", "WUM", "WUN", "WUR", "WW",
+    "WZ", "WZL", "WÜ", "X", "Y", "Z", "ZE", "ZEL", "ZI", "ZIG", "ZP", "ZR",
+    "ZS", "ZW", "ZZ", "ÖHR", "ÜB",
+]);

package/dist/esm/rules/engine.d.ts

@@ -1,4 +1,5 @@
-import { type Detection } from "../types.js";
+import { type CountryEvidence, type Detection } from "../types.js";
+import { type RawMatch } from "./matchers.js";
 /**
  * The country modules use the EU/VAT convention (UK, EL) while the public
  * contract is ISO 3166-1 alpha-2 (GB, GR). Accept both spellings so a caller
@@ -12,11 +13,34 @@ export declare class RuleEngine {
     private loadedCountries;
     addCustomPattern(name: string, pattern: string): void;
     loadCountries(countryCodes: string[] | null): void;
-    detect(text: string, countryCodes: string[] | null): Detection[];
+    /**
+     * Generate candidate matches. Country-blind, by contract.
+     *
+     * This is the only caller of {@link MultiPatternMatcher.scan}, and it takes
+     * no country argument. Which country the caller declared may influence how a
+     * match is *scored*; it may never influence whether the match is *found*.
+     * Before this held, `countries: ["BE"]` made a valid Dutch BSN vanish
+     * entirely because the Dutch patterns were never run.
+     */
+    generateCandidates(text: string): RawMatch[];
+    detect(text: string, countryCodes: string[] | null, countryHint?: string[] | null): Detection[];
+    /**
+     * {@link RuleEngine.detect}, plus the country evidence it reasoned from.
+     *
+     * `countryCodes` is **scope**: it flags detections from elsewhere as
+     * `outOfScope` and, like `countryHint`, contributes a prior. `countryHint` is
+     * **only** a prior — it helps resolve ambiguity without marking anything out
+     * of scope. Neither gates what is looked for.
+     */
+    detectWithEvidence(text: string, countryCodes: string[] | null, countryHint?: string[] | null, priorEvidence?: CountryEvidence[] | null): {
+        detections: Detection[];
+        evidence: CountryEvidence[];
+        scores: Map<string, number>;
+    };
     /**
      * Remove overlapping detections with priority-aware resolution.
-     * Priority: validated (3) > custom (2) > regex-only (1).
-     * Within the same tier, longer span wins.
+     * Priority: validated (3) > custom (2) > regex-only (1) > postal (0) >
+     * demoted (-1). Within a tier, longer span wins, then country evidence.
      */
     private deduplicate;
     getLoadedCountries(): Set<string>;