euredact 0.3.2 → 0.3.4

package/dist/cjs/rules/context.js

@@ -39,8 +39,20 @@ class DocumentContext {
             this.items.push(chunkOffset === 0 ? ev : { ...ev, span });
         }
     }
-    /** Everything recorded so far, spans rebased to the whole document. */
-    evidence() {
+    /**
+     * Everything recorded so far, spans rebased to the whole document.
+     *
+     * A getter, to match {@link DocumentContext.size}. These were a method and a
+     * getter on the same class, which is a trip hazard rather than a style
+     * question: `ctx.size()` and `ctx.evidence` both *succeed* and return
+     * something useless — a number is not callable, and a function object is
+     * truthy — so the mistake surfaces later as an empty result rather than as
+     * an error. Both are property reads now, and the wrong form throws.
+     *
+     * Returns a fresh copy each call, so mutating it cannot corrupt the context.
+     * (The Python SDK spells this `evidence()`, following its own idiom.)
+     */
+    get evidence() {
         return [...this.items];
     }
     get size() {

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

@@ -226,7 +226,7 @@ const DE = {
         p(types_js_1.EntityType.LICENSE_PLATE, String.raw `\b[A-ZÄÖÜ]{1,3}[\s\-][A-Z]{1,2}[\s\-]?\d{1,4}[EH]?\b`),
         p(types_js_1.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(types_js_1.EntityType.CHAMBER_OF_COMMERCE, String.raw `\bHR[AB]\s?\d{4,6}\b`),
-        p(types_js_1.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),
+        p(types_js_1.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", "SVNR", "SV-Nr", "RVNR"], true),
         p(types_js_1.EntityType.TAX_ID, String.raw `\b\d{2,3}/\d{3,4}/\d{4,5}\b`, null, "", ["Steuernummer", "St.-Nr", "StNr", "Finanzamt", "Steuer"], true),
         p(types_js_1.EntityType.TAX_ID, String.raw `\b\d{13}\b`, null, "", ["Steuernummer", "St.-Nr", "StNr", "Finanzamt", "Steuer"], true),
         p(types_js_1.EntityType.HEALTH_INSURANCE, String.raw `\b[A-Z]\d{9}\b`, null, "", ["Versichertennummer", "Krankenversicherung", "KV-Nummer", "Krankenkasse", "GKV", "Versichertenkarte", "Versicherter", "Versicherte", "KVNR", "Krankenversichertennummer"], true),

package/dist/cjs/rules/engine.js

@@ -253,6 +253,23 @@ class RuleEngine {
             else
                 zonesByType.set(f.etype, [[f.start, f.end]]);
         }
+        // Any type, strict subset: a candidate covering only *part* of a rejected
+        // identifier is a fragment of it, not a different entity. The generic
+        // separator-tolerant phone pattern claimed characters 3-14 of the rejected
+        // Belgian national number in "Rijksregisternummer: 85.03.19-284.73" and
+        // reported it as a PHONE. An equal span is two schemes competing for the
+        // whole value; a strict subset is one picking over another's wreckage.
+        //
+        // Deliberately ignores corroboration and uses every failed span, because it
+        // *removes* candidates and must therefore be country-blind — gating it on
+        // the document's countries would make the set of spans found depend on
+        // `countries`, which is invariant I1.
+        //
+        // Kept unmerged: merging adjacent spans would invent strict-subset
+        // relationships that neither original span had.
+        const allFailed = failedSpans
+            .map(f => [f.start, f.end])
+            .sort((a, b) => a[0] - b[0] || a[1] - b[1]);
         const mergedZones = new Map();
         for (const [etype, spans] of zonesByType) {
             spans.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
@@ -299,9 +316,28 @@ class RuleEngine {
                     demoted = idx >= 0 && zone.ends[idx] >= match.end;
                 }
             }
+            // Dropped rather than demoted. Demotion cannot help here: nothing else
+            // wants a fragment, so a demoted candidate still wins its span by
+            // default — the generic phone pattern kept claiming the tail of the
+            // rejected national number.
+            if (match.patternDef.validator === null && !demoted) {
+                let fragment = false;
+                for (const [zs, ze] of allFailed) {
+                    if (zs > match.start)
+                        break;
+                    if (match.end <= ze && (match.start > zs || match.end < ze)) {
+                        fragment = true;
+                        break;
+                    }
+                }
+                if (fragment)
+                    continue;
+            }
             let priority;
+            let blindPriority;
             if (demoted) {
                 priority = -1;
+                blindPriority = -1;
             }
             else if (hasValidValidator) {
                 // A passing checksum normally outranks everything. But a checksum only
@@ -315,9 +351,11 @@ class RuleEngine {
                 // themselves — an IBAN emits evidence for its own country — so a
                 // foreign IBAN in a domestic invoice keeps its rank.
                 priority = corroborated(match.countryCode) ? 3 : 1;
+                blindPriority = 3;
             }
             else if (match.countryCode === "CUSTOM") {
                 priority = 2;
+                blindPriority = 2;
             }
             else if (match.patternDef.entityType === types_js_1.EntityType.POSTAL_CODE) {
                 // A bare digit run is the weakest evidence in the engine and must never
@@ -325,13 +363,16 @@ class RuleEngine {
                 // BANK_ACCOUNT, VAT...). Postal codes take unclaimed spans only,
                 // whatever the span lengths.
                 priority = 0;
+                blindPriority = 0;
             }
             else {
                 priority = 1;
+                blindPriority = 1;
             }
             const country = (match.countryCode !== "SHARED" && match.countryCode !== "CUSTOM")
                 ? match.countryCode : null;
             candidates.push({
+                blindPriority,
                 priority,
                 length: match.end - match.start,
                 countryScore: countryScores.get(match.countryCode) ?? 0,
@@ -349,7 +390,8 @@ class RuleEngine {
             });
         }
         for (const d of (0, structural_js_1.detectStructuralDob)(text)) {
-            candidates.push({ priority: 1, length: d.end - d.start, countryScore: 0, inScope: 1, det: d });
+            candidates.push({ blindPriority: 1, priority: 1, length: d.end - d.start,
+                countryScore: 0, inScope: 1, det: d });
         }
         const detections = this.deduplicate(candidates);
         detections.sort((a, b) => a.start - b.start || b.end - a.end);
@@ -370,16 +412,50 @@ class RuleEngine {
     deduplicate(candidates) {
         if (candidates.length === 0)
             return [];
-        // Span length outranks scope: preferring the declared country over the
-        // longest match can truncate an entity. Measured: with countries ["BE"],
-        // the Belgian phone pattern claims 11 of the 14 characters of
-        // "06 12 34 56 78" and leaves three digits exposed. Scope only breaks ties
-        // between candidates of equal length, so it can change WHICH country is
-        // attributed, never WHAT is masked.
-        const sorted = [...candidates].sort((a, b) => b.priority - a.priority ||
-            b.length - a.length ||
-            b.countryScore - a.countryScore ||
-            b.inScope - a.inScope);
+        // The structural tier is a property of the *span*, not of the candidate:
+        // the best tier anything claiming those exact characters can offer. Used
+        // per candidate it would also discriminate *within* a span, where the
+        // country-aware tier must have the final word — that silently disabled
+        // country inference entirely in the Python SDK, handing every ambiguous
+        // value to whichever foreign scheme happened to validate.
+        const spanTier = new Map();
+        for (const c of candidates) {
+            const key = `${c.det.start}:${c.det.end}`;
+            const seen = spanTier.get(key);
+            if (seen === undefined || c.blindPriority > seen)
+                spanTier.set(key, c.blindPriority);
+        }
+        const tierOf = (c) => spanTier.get(`${c.det.start}:${c.det.end}`);
+        // Span length outranks *everything*, including validation.
+        //
+        // A shorter candidate winning re-cuts a longer one and leaves the
+        // remainder in the clear, which is a leak. Two measured cases:
+        //
+        //   "06 12 34 56 78"   the Belgian phone pattern claimed 11 of 14
+        //                      characters and exposed three digits
+        //   "194.232.104.77"   the Dutch national-ID pattern validates on
+        //                      "194.232.104" and outranked the IP address,
+        //                      leaving ".77" in the output
+        //
+        // The second also broke invariant I1 in the Python SDK, where promotion
+        // depends on whether the document corroborates the country, so `countries`
+        // decided which span won. Ranking length first removes both — a redaction
+        // tool masking more than it must is recoverable; masking less is not.
+        //
+        // Priority still decides between candidates of *equal* length, which is
+        // where it matters: a valid IBAN beats a coincidental phone match on the
+        // same characters.
+        // Ordering between *different* spans is country-blind; the country only
+        // ever picks the winner among candidates covering the *same* span. That
+        // split makes invariant I1 structural rather than merely tested: the key is
+        // country-blind up to and including `start`, and (length, start) already
+        // identifies a span uniquely.
+        const sorted = [...candidates].sort((a, b) => b.length - a.length || // longest first     } country-blind
+            tierOf(b) - tierOf(a) || // best tier here    } — decides
+            a.det.start - b.det.start || // leftmost          } WHICH span
+            b.priority - a.priority || // country priority  } country-aware
+            b.countryScore - a.countryScore || // country evidence  } — decides the
+            b.inScope - a.inScope); // declared scope    } LABEL only
         const result = [];
         const occupied = new Set();
         for (const { det } of sorted) {

package/dist/cjs/sdk.js

@@ -24,6 +24,32 @@ class ReferentialMapper {
     }
 }
 const DEFAULT_MAX_INPUT_LENGTH = 10_485_760; // ~10 MB of text
+/**
+ * Reject a bare string where a list of country codes is expected.
+ *
+ * `countries: "NL"` is iterable, so it walks into the codes "N" and "L".
+ * Neither resolves, so nothing is declared — and every detection that *does*
+ * carry a country is then flagged `outOfScope`. A caller following the
+ * documented pattern of filtering on that field silently keeps none of them,
+ * while `redactedText` still looks perfectly correct. The failure direction is
+ * "no PII here", from a one-character typo.
+ *
+ * This already threw in Node, but by accident and only once something happened
+ * to call `.map` on it — deep in the call, with a message naming neither the
+ * argument nor the fix.
+ *
+ * A wrong *code* is data and only warns; raising there would invite callers to
+ * wrap redaction in try/catch and skip it. A wrong *type* is a programming
+ * error with no correct interpretation to fall back on.
+ */
+function checkCountryArg(value, param) {
+    if (typeof value === "string") {
+        throw new TypeError(`${param} must be an array of country codes, not a bare string. ` +
+            `Pass ${param}: ["${value}"] rather than ${param}: "${value}" — a string ` +
+            `is iterated character by character, which silently declares nothing and ` +
+            `flags every detection outOfScope.`);
+    }
+}
 class EuRedact {
     engine = new engine_js_1.RuleEngine();
     cache = new cache_js_1.ResultCache();
@@ -43,6 +69,8 @@ class EuRedact {
         this.referentialMapper.clear();
     }
     redact(text, options = {}) {
+        checkCountryArg(options.countries, "countries");
+        checkCountryArg(options.countryHint, "countryHint");
         if (text.length > this.maxInputLength) {
             throw new Error(`Input text length (${text.length.toLocaleString()} chars) exceeds the maximum ` +
                 `(${this.maxInputLength.toLocaleString()} chars). Split the input or ` +
@@ -67,7 +95,7 @@ class EuRedact {
             if (cached !== null)
                 return cached;
         }
-        const { detections: rawDetections, evidence, scores, } = this.engine.detectWithEvidence(normalizedText, countries, countryHint, context !== null ? context.evidence() : null);
+        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;

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

@@ -25,7 +25,19 @@ export declare class DocumentContext {
     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[];
+    /**
+     * Everything recorded so far, spans rebased to the whole document.
+     *
+     * A getter, to match {@link DocumentContext.size}. These were a method and a
+     * getter on the same class, which is a trip hazard rather than a style
+     * question: `ctx.size()` and `ctx.evidence` both *succeed* and return
+     * something useless — a number is not callable, and a function object is
+     * truthy — so the mistake surfaces later as an empty result rather than as
+     * an error. Both are property reads now, and the wrong form throws.
+     *
+     * Returns a fresh copy each call, so mutating it cannot corrupt the context.
+     * (The Python SDK spells this `evidence()`, following its own idiom.)
+     */
+    get evidence(): CountryEvidence[];
     get size(): number;
 }

package/dist/esm/rules/context.js

@@ -36,8 +36,20 @@ export class DocumentContext {
             this.items.push(chunkOffset === 0 ? ev : { ...ev, span });
         }
     }
-    /** Everything recorded so far, spans rebased to the whole document. */
-    evidence() {
+    /**
+     * Everything recorded so far, spans rebased to the whole document.
+     *
+     * A getter, to match {@link DocumentContext.size}. These were a method and a
+     * getter on the same class, which is a trip hazard rather than a style
+     * question: `ctx.size()` and `ctx.evidence` both *succeed* and return
+     * something useless — a number is not callable, and a function object is
+     * truthy — so the mistake surfaces later as an empty result rather than as
+     * an error. Both are property reads now, and the wrong form throws.
+     *
+     * Returns a fresh copy each call, so mutating it cannot corrupt the context.
+     * (The Python SDK spells this `evidence()`, following its own idiom.)
+     */
+    get evidence() {
         return [...this.items];
     }
     get size() {

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

@@ -223,7 +223,7 @@ const DE = {
         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),
+        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", "SVNR", "SV-Nr", "RVNR"], true),
         p(EntityType.TAX_ID, String.raw `\b\d{2,3}/\d{3,4}/\d{4,5}\b`, null, "", ["Steuernummer", "St.-Nr", "StNr", "Finanzamt", "Steuer"], true),
         p(EntityType.TAX_ID, String.raw `\b\d{13}\b`, null, "", ["Steuernummer", "St.-Nr", "StNr", "Finanzamt", "Steuer"], true),
         p(EntityType.HEALTH_INSURANCE, String.raw `\b[A-Z]\d{9}\b`, null, "", ["Versichertennummer", "Krankenversicherung", "KV-Nummer", "Krankenkasse", "GKV", "Versichertenkarte", "Versicherter", "Versicherte", "KVNR", "Krankenversichertennummer"], true),

package/dist/esm/rules/engine.js

@@ -216,6 +216,23 @@ export class RuleEngine {
             else
                 zonesByType.set(f.etype, [[f.start, f.end]]);
         }
+        // Any type, strict subset: a candidate covering only *part* of a rejected
+        // identifier is a fragment of it, not a different entity. The generic
+        // separator-tolerant phone pattern claimed characters 3-14 of the rejected
+        // Belgian national number in "Rijksregisternummer: 85.03.19-284.73" and
+        // reported it as a PHONE. An equal span is two schemes competing for the
+        // whole value; a strict subset is one picking over another's wreckage.
+        //
+        // Deliberately ignores corroboration and uses every failed span, because it
+        // *removes* candidates and must therefore be country-blind — gating it on
+        // the document's countries would make the set of spans found depend on
+        // `countries`, which is invariant I1.
+        //
+        // Kept unmerged: merging adjacent spans would invent strict-subset
+        // relationships that neither original span had.
+        const allFailed = failedSpans
+            .map(f => [f.start, f.end])
+            .sort((a, b) => a[0] - b[0] || a[1] - b[1]);
         const mergedZones = new Map();
         for (const [etype, spans] of zonesByType) {
             spans.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
@@ -262,9 +279,28 @@ export class RuleEngine {
                     demoted = idx >= 0 && zone.ends[idx] >= match.end;
                 }
             }
+            // Dropped rather than demoted. Demotion cannot help here: nothing else
+            // wants a fragment, so a demoted candidate still wins its span by
+            // default — the generic phone pattern kept claiming the tail of the
+            // rejected national number.
+            if (match.patternDef.validator === null && !demoted) {
+                let fragment = false;
+                for (const [zs, ze] of allFailed) {
+                    if (zs > match.start)
+                        break;
+                    if (match.end <= ze && (match.start > zs || match.end < ze)) {
+                        fragment = true;
+                        break;
+                    }
+                }
+                if (fragment)
+                    continue;
+            }
             let priority;
+            let blindPriority;
             if (demoted) {
                 priority = -1;
+                blindPriority = -1;
             }
             else if (hasValidValidator) {
                 // A passing checksum normally outranks everything. But a checksum only
@@ -278,9 +314,11 @@ export class RuleEngine {
                 // themselves — an IBAN emits evidence for its own country — so a
                 // foreign IBAN in a domestic invoice keeps its rank.
                 priority = corroborated(match.countryCode) ? 3 : 1;
+                blindPriority = 3;
             }
             else if (match.countryCode === "CUSTOM") {
                 priority = 2;
+                blindPriority = 2;
             }
             else if (match.patternDef.entityType === EntityType.POSTAL_CODE) {
                 // A bare digit run is the weakest evidence in the engine and must never
@@ -288,13 +326,16 @@ export class RuleEngine {
                 // BANK_ACCOUNT, VAT...). Postal codes take unclaimed spans only,
                 // whatever the span lengths.
                 priority = 0;
+                blindPriority = 0;
             }
             else {
                 priority = 1;
+                blindPriority = 1;
             }
             const country = (match.countryCode !== "SHARED" && match.countryCode !== "CUSTOM")
                 ? match.countryCode : null;
             candidates.push({
+                blindPriority,
                 priority,
                 length: match.end - match.start,
                 countryScore: countryScores.get(match.countryCode) ?? 0,
@@ -312,7 +353,8 @@ export class RuleEngine {
             });
         }
         for (const d of detectStructuralDob(text)) {
-            candidates.push({ priority: 1, length: d.end - d.start, countryScore: 0, inScope: 1, det: d });
+            candidates.push({ blindPriority: 1, priority: 1, length: d.end - d.start,
+                countryScore: 0, inScope: 1, det: d });
         }
         const detections = this.deduplicate(candidates);
         detections.sort((a, b) => a.start - b.start || b.end - a.end);
@@ -333,16 +375,50 @@ export class RuleEngine {
     deduplicate(candidates) {
         if (candidates.length === 0)
             return [];
-        // Span length outranks scope: preferring the declared country over the
-        // longest match can truncate an entity. Measured: with countries ["BE"],
-        // the Belgian phone pattern claims 11 of the 14 characters of
-        // "06 12 34 56 78" and leaves three digits exposed. Scope only breaks ties
-        // between candidates of equal length, so it can change WHICH country is
-        // attributed, never WHAT is masked.
-        const sorted = [...candidates].sort((a, b) => b.priority - a.priority ||
-            b.length - a.length ||
-            b.countryScore - a.countryScore ||
-            b.inScope - a.inScope);
+        // The structural tier is a property of the *span*, not of the candidate:
+        // the best tier anything claiming those exact characters can offer. Used
+        // per candidate it would also discriminate *within* a span, where the
+        // country-aware tier must have the final word — that silently disabled
+        // country inference entirely in the Python SDK, handing every ambiguous
+        // value to whichever foreign scheme happened to validate.
+        const spanTier = new Map();
+        for (const c of candidates) {
+            const key = `${c.det.start}:${c.det.end}`;
+            const seen = spanTier.get(key);
+            if (seen === undefined || c.blindPriority > seen)
+                spanTier.set(key, c.blindPriority);
+        }
+        const tierOf = (c) => spanTier.get(`${c.det.start}:${c.det.end}`);
+        // Span length outranks *everything*, including validation.
+        //
+        // A shorter candidate winning re-cuts a longer one and leaves the
+        // remainder in the clear, which is a leak. Two measured cases:
+        //
+        //   "06 12 34 56 78"   the Belgian phone pattern claimed 11 of 14
+        //                      characters and exposed three digits
+        //   "194.232.104.77"   the Dutch national-ID pattern validates on
+        //                      "194.232.104" and outranked the IP address,
+        //                      leaving ".77" in the output
+        //
+        // The second also broke invariant I1 in the Python SDK, where promotion
+        // depends on whether the document corroborates the country, so `countries`
+        // decided which span won. Ranking length first removes both — a redaction
+        // tool masking more than it must is recoverable; masking less is not.
+        //
+        // Priority still decides between candidates of *equal* length, which is
+        // where it matters: a valid IBAN beats a coincidental phone match on the
+        // same characters.
+        // Ordering between *different* spans is country-blind; the country only
+        // ever picks the winner among candidates covering the *same* span. That
+        // split makes invariant I1 structural rather than merely tested: the key is
+        // country-blind up to and including `start`, and (length, start) already
+        // identifies a span uniquely.
+        const sorted = [...candidates].sort((a, b) => b.length - a.length || // longest first     } country-blind
+            tierOf(b) - tierOf(a) || // best tier here    } — decides
+            a.det.start - b.det.start || // leftmost          } WHICH span
+            b.priority - a.priority || // country priority  } country-aware
+            b.countryScore - a.countryScore || // country evidence  } — decides the
+            b.inScope - a.inScope); // declared scope    } LABEL only
         const result = [];
         const occupied = new Set();
         for (const { det } of sorted) {

package/dist/esm/sdk.js

@@ -21,6 +21,32 @@ class ReferentialMapper {
     }
 }
 const DEFAULT_MAX_INPUT_LENGTH = 10_485_760; // ~10 MB of text
+/**
+ * Reject a bare string where a list of country codes is expected.
+ *
+ * `countries: "NL"` is iterable, so it walks into the codes "N" and "L".
+ * Neither resolves, so nothing is declared — and every detection that *does*
+ * carry a country is then flagged `outOfScope`. A caller following the
+ * documented pattern of filtering on that field silently keeps none of them,
+ * while `redactedText` still looks perfectly correct. The failure direction is
+ * "no PII here", from a one-character typo.
+ *
+ * This already threw in Node, but by accident and only once something happened
+ * to call `.map` on it — deep in the call, with a message naming neither the
+ * argument nor the fix.
+ *
+ * A wrong *code* is data and only warns; raising there would invite callers to
+ * wrap redaction in try/catch and skip it. A wrong *type* is a programming
+ * error with no correct interpretation to fall back on.
+ */
+function checkCountryArg(value, param) {
+    if (typeof value === "string") {
+        throw new TypeError(`${param} must be an array of country codes, not a bare string. ` +
+            `Pass ${param}: ["${value}"] rather than ${param}: "${value}" — a string ` +
+            `is iterated character by character, which silently declares nothing and ` +
+            `flags every detection outOfScope.`);
+    }
+}
 export class EuRedact {
     engine = new RuleEngine();
     cache = new ResultCache();
@@ -40,6 +66,8 @@ export class EuRedact {
         this.referentialMapper.clear();
     }
     redact(text, options = {}) {
+        checkCountryArg(options.countries, "countries");
+        checkCountryArg(options.countryHint, "countryHint");
         if (text.length > this.maxInputLength) {
             throw new Error(`Input text length (${text.length.toLocaleString()} chars) exceeds the maximum ` +
                 `(${this.maxInputLength.toLocaleString()} chars). Split the input or ` +
@@ -64,7 +92,7 @@ export class EuRedact {
             if (cached !== null)
                 return cached;
         }
-        const { detections: rawDetections, evidence, scores, } = this.engine.detectWithEvidence(normalizedText, countries, countryHint, context !== null ? context.evidence() : null);
+        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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euredact",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "European PII redaction SDK -- fast, zero-dependency, rule-based detection and redaction of personal data across 31 European countries",
   "license": "Apache-2.0",
   "type": "module",
@@ -60,7 +60,8 @@
     "test:eval": "node --import tsx src/__tests__/run.ts",
     "test:eval:full": "node --max-old-space-size=8192 --import tsx src/__tests__/evalFull.ts",
     "test:conformance": "node --import tsx src/__tests__/conformance.ts",
-    "test:inference": "node --import tsx src/__tests__/inference.ts"
+    "test:inference": "node --import tsx src/__tests__/inference.ts",
+    "dump": "node --import tsx src/__tests__/dump.ts"
   },
   "devDependencies": {
     "typescript": "^5.4.0",