mobiletic-labs/anonymizer
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat!: optional fail-closed fallback, legend output, richer prompt & docs

Browse Source 
BREAKING CHANGE: regex fallback is now opt-in (patterns no longer defaults
to presets.swiss). With no fallback an LLM failure throws AnonymizationError
(fail-closed) and the pre-filter is bypassed; at least one of llm/patterns is
required. AnonymizationResult gains a required `legend`; anonymizeChunks seed
is now { mapping, legend? } and returns legend.

- prompt: model may coin new UPPERCASE abbreviations and returns a 'legende'
  explaining every abbreviation used (French); backfilled by DEFAULT_LEGEND
- PatternDef.meaning surfaces in the legend; swiss/generic presets get meanings
- AnonymizationError (exported) wraps the cause on fail-closed
- README: drop the chatbot provenance line; add 'How it works' + nLPD sections
- 34 tests / 99% coverage; bump to 0.2.0

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Mobiletic
2026-06-25 15:28:04 +01:00
parent 08f84ae14a
commit 669794522e
13 changed files with 408 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
test/anonymizer.test.ts
View File

@@ -1,5 +1,5 @@
import { describe, it, expect, vi } from 'vitest';
import { Anonymizer, presets, type LlmProvider } from '../src/index.js';
import { Anonymizer, AnonymizationError, presets, type LlmProvider } from '../src/index.js';
/** An LLM provider that is configured but always fails → forces the regex fallback. */
const failingLlm = (overrides: Partial<LlmProvider> = {}): LlmProvider => ({
@@ -50,7 +50,7 @@ describe('Anonymizer (Swiss preset)', () => {
it('PII-free chunks → no LLM call, returned as-is', async () => {
const llm = failingLlm();
const s = new Anonymizer({ llm, patterns: presets.swiss });
const r = await s.anonymizeChunks(['Un INNER JOIN combine deux tables.'], {});
const r = await s.anonymizeChunks(['Un INNER JOIN combine deux tables.'], { mapping: {} });
expect(llm.anonymizeBatch).not.toHaveBeenCalled();
expect(r.anon[0]).toContain('INNER JOIN');
expect(r.mapping).toEqual({});
@@ -60,7 +60,7 @@ describe('Anonymizer (Swiss preset)', () => {
const llm = failingLlm();
const s = new Anonymizer({ llm, patterns: presets.swiss });
const seed = { '[PER_1.NOM:M]': 'Alain JACCARD' };
const r = await s.anonymizeChunks(['Le dossier de Alain JACCARD est complet.'], seed);
const r = await s.anonymizeChunks(['Le dossier de Alain JACCARD est complet.'], { mapping: seed });
expect(llm.anonymizeBatch).not.toHaveBeenCalled();
expect(r.anon[0]).toContain('[PER_1.NOM:M]');
expect(r.anon[0]).not.toContain('Alain JACCARD');
@@ -71,19 +71,22 @@ describe('Anonymizer (Swiss preset)', () => {
const anonymizeBatch = vi.fn().mockResolvedValue({
segments: ['[PER_1.NOM:M] a signé.'],
mapping: { '[PER_1.NOM:M]': 'Bob Martin' },
legend: { PER: 'Personne', NOM: 'Nom de famille', M: 'Masculin' },
});
const s = new Anonymizer({ llm: failingLlm({ anonymizeBatch }), patterns: presets.swiss });
const seed = { '[PER_1.NOM:M]': 'Alain JACCARD' };
const r = await s.anonymizeChunks(['Bob Martin a signé.'], seed);
const r = await s.anonymizeChunks(['Bob Martin a signé.'], { mapping: seed });
expect(anonymizeBatch).toHaveBeenCalledTimes(1);
expect(r.anon[0]).toContain('[PER_2.NOM:M]');
expect(r.mapping['[PER_1.NOM:M]']).toBe('Alain JACCARD');
expect(r.mapping['[PER_2.NOM:M]']).toBe('Bob Martin');
// legend covers the abbreviations used in the anonymized chunk
expect(r.legend).toMatchObject({ PER: 'Personne', NOM: 'Nom de famille', M: 'Masculin' });
});
it('falls back to regex (structured ids) when the LLM is unavailable', async () => {
const s = new Anonymizer({ llm: failingLlm(), patterns: presets.swiss });
const r = await s.anonymizeChunks(['Contact : jean@exemple.ch'], {});
const r = await s.anonymizeChunks(['Contact : jean@exemple.ch'], { mapping: {} });
expect(r.anon[0]).not.toContain('jean@exemple.ch');
expect(Object.values(r.mapping)).toContain('jean@exemple.ch');
});
@@ -121,4 +124,58 @@ describe('Anonymizer (Swiss preset)', () => {
expect(r.mapping['[TICKET_1]']).toBe('JIRA-123');
});
});
describe('legend', () => {
it('the regex fallback produces a French legend from tag meanings', async () => {
const s = new Anonymizer({ patterns: presets.swiss });
const r = await s.anonymize('Écris à jean@exemple.ch');
expect(r.legend).toEqual({ EMAIL: 'Adresse e-mail' });
});
it('backfills a missing legend entry from the built-in default (LLM omitted it)', async () => {
const anonymize = vi.fn().mockResolvedValue({
anon: 'Dossier de [PER_1.NOM:M]',
mapping: { '[PER_1.NOM:M]': 'Alain Jaccard' },
legend: {}, // model returned no legend
});
const s = new Anonymizer({ llm: failingLlm({ anonymize }), patterns: presets.swiss });
const r = await s.anonymize('Dossier de Alain Jaccard');
expect(r.legend).toEqual({ PER: 'Personne', NOM: 'Nom de famille', M: 'Masculin' });
});
it('a custom tag with a meaning surfaces it in the legend', async () => {
const s = new Anonymizer({
patterns: [{ tag: 'TICKET', re: /\bJIRA-\d+\b/g, meaning: 'Ticket de suivi' }],
});
const r = await s.anonymize('Voir JIRA-123');
expect(r.legend).toEqual({ TICKET: 'Ticket de suivi' });
});
});
describe('fail-closed (optional fallback)', () => {
it('throws if neither an LLM nor patterns are provided', () => {
expect(() => new Anonymizer({})).toThrowError(AnonymizationError);
});
it('LLM-only: a provider failure throws AnonymizationError with the cause', async () => {
const cause = new Error('LLM_HTTP_500');
const s = new Anonymizer({ llm: failingLlm({ anonymize: vi.fn().mockRejectedValue(cause) }) });
await expect(s.anonymize('Contact: jean@exemple.ch')).rejects.toBeInstanceOf(AnonymizationError);
await expect(s.anonymize('Contact: jean@exemple.ch')).rejects.toMatchObject({ cause });
});
it('LLM-only: bypasses the pre-filter so PII-free text still hits the provider', async () => {
const anonymize = vi.fn().mockResolvedValue({ anon: 'INNER JOIN', mapping: {}, legend: {} });
const s = new Anonymizer({ llm: failingLlm({ anonymize }) });
await s.anonymize('Explique INNER JOIN'); // no structured PII, no name hint
expect(anonymize).toHaveBeenCalledTimes(1);
});
it('LLM-only: anonymizeChunks rejects with AnonymizationError on provider failure', async () => {
const s = new Anonymizer({ llm: failingLlm() }); // anonymizeBatch rejects
await expect(s.anonymizeChunks(['Bob Martin a signé.'], { mapping: {} })).rejects.toBeInstanceOf(
AnonymizationError,
);
});
});
});