fuseji 0.1.0__py3-none-any.whl

fuseji/__init__.py

@@ -0,0 +1,28 @@
+"""fuseji — 日本語特化の PII 検出・マスキングミドルウェア."""
+
+from . import entity_types
+from .engine import Masker
+from .exceptions import FusejiError, InvalidConfigError, InvalidEntityError
+from .strategies import Hash, MaskStrategy, Placeholder, Redact, VaultStrategy
+from .types import Entity, MaskResult
+from .vault import InMemoryVault, Vault
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Entity",
+    "FusejiError",
+    "Hash",
+    "InMemoryVault",
+    "InvalidConfigError",
+    "InvalidEntityError",
+    "MaskResult",
+    "MaskStrategy",
+    "Masker",
+    "Placeholder",
+    "Redact",
+    "Vault",
+    "VaultStrategy",
+    "__version__",
+    "entity_types",
+]

fuseji/engine.py

@@ -0,0 +1,176 @@
+"""Masker エンジン — 認識器・NER を統合し、戦略でテキストをマスクする."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from .recognizers.base import default_recognizers
+from .strategies import Placeholder, VaultStrategy
+from .types import Entity, MaskResult
+
+if TYPE_CHECKING:
+    from .ner.base import NerBackend
+    from .recognizers.base import Recognizer
+    from .strategies import MaskStrategy
+    from .vault import Vault
+
+# mask_json の再帰深度制限。深いネストでスタック消費を防ぐための fail-closed 値。
+DEFAULT_MAX_JSON_DEPTH: int = 100
+# 深度超過時に返す固定 placeholder。fail-closed として原データを返さない。
+_TOO_DEEP_PLACEHOLDER: str = "[fuseji: too deep]"
+
+
+class Masker:
+    """fuseji の中核クラス。
+
+    認識器（正規表現/checksum）と NER バックエンドを統合し、検出した
+    PII エンティティを戦略でマスクする。
+
+    Args:
+        recognizers: 使用する認識器。`None` で v0.1 のデフォルトセット。
+        ner: NER バックエンド（GiNZA 等）。`None` で NER 無効。
+        strategy: マスキング戦略（Placeholder/Redact/Hash）。Vault 指定時は
+            `VaultStrategy` で自動的に置き換えられ、本引数は無視される
+            （両者を同時指定すると `UserWarning` が発行される）。
+        threshold: このスコア未満のエンティティは除外する。recall 重視で 0.4。
+        vault: 仮名化バウルト。指定時は `VaultStrategy(vault=vault)` が
+            内部戦略として使われ、同一表層形は同一 placeholder。excluded type
+            は番号なし `<TYPE>` 形式でマスクし、mapping に残らない。
+        max_json_depth: `mask_json` の再帰深度上限。超過時は fail-closed で
+            `"[fuseji: too deep]"` に置換される。
+
+    Example:
+        基本的な使い方:
+
+        >>> from fuseji import Masker
+        >>> masker = Masker()
+        >>> result = masker.mask("メール: taro@example.co.jp、電話 090-1234-5678")
+        >>> print(result.text)
+        メール: <EMAIL_1>、電話 <JP_PHONE_NUMBER_1>
+
+        Redact 戦略で固定文字列に:
+
+        >>> from fuseji import Masker, Redact
+        >>> masker = Masker(strategy=Redact())
+        >>> masker.mask("a@b.com").text
+        '[REDACTED]'
+
+        Vault で復元可能なマスキング:
+
+        >>> from fuseji import Masker, InMemoryVault
+        >>> vault = InMemoryVault()
+        >>> masker = Masker(vault=vault)
+        >>> r = masker.mask("a@b.com への返信")
+        >>> vault.restore(r.text)
+        'a@b.com への返信'
+    """
+
+    def __init__(
+        self,
+        recognizers: Sequence[Recognizer] | None = None,
+        ner: NerBackend | None = None,
+        strategy: MaskStrategy | None = None,
+        threshold: float = 0.4,
+        vault: Vault | None = None,
+        max_json_depth: int = DEFAULT_MAX_JSON_DEPTH,
+    ) -> None:
+        self._recognizers: tuple[Recognizer, ...] = (
+            tuple(recognizers) if recognizers is not None else default_recognizers()
+        )
+        self._ner = ner
+        # vault があれば VaultStrategy で吸収し、戦略経路を単一化する。
+        # strategy 引数は vault と排他（vault 優先、strategy 無視）。
+        if vault is not None:
+            if strategy is not None:
+                warnings.warn(
+                    "Masker: strategy と vault が同時指定されました。"
+                    "vault を優先して strategy は無視されます。"
+                    "両者を明確に分離するには Masker(vault=...) または "
+                    "Masker(strategy=...) のいずれか一方のみ指定してください。",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            self._strategy: MaskStrategy = VaultStrategy(vault=vault)
+        else:
+            self._strategy = strategy if strategy is not None else Placeholder()
+        self._threshold = threshold
+        self._max_json_depth = max_json_depth
+
+    def detect(self, text: str) -> tuple[Entity, ...]:
+        """テキストから PII エンティティを検出し、threshold で絞り込んだ後、
+        オーバーラップをスコア優先で解決して返す。
+
+        Example:
+            >>> from fuseji import Masker
+            >>> entities = Masker().detect("メール a@b.com 電話 090-1234-5678")
+            >>> sorted({e.type for e in entities})
+            ['EMAIL', 'JP_PHONE_NUMBER']
+        """
+        raw: list[Entity] = []
+        for r in self._recognizers:
+            raw.extend(r.analyze(text))
+        if self._ner is not None:
+            raw.extend(self._ner.analyze(text))
+        filtered = [e for e in raw if e.score >= self._threshold]
+        return tuple(_resolve_overlaps(filtered))
+
+    def mask(self, text: str) -> MaskResult:
+        """テキストをマスクして MaskResult を返す。"""
+        entities = self.detect(text)
+        masked_text, mapping = self._strategy.mask(text, entities)
+        return MaskResult(text=masked_text, entities=entities, mapping=mapping)
+
+    def mask_json(self, data: Any) -> Any:
+        """JSON 互換のデータ構造を再帰的にマスクして返す。
+
+        対象: str（mask() を適用）, dict（値のみ再帰）, list/tuple（要素を再帰）。
+        その他の型（int, float, bool, None など）は素通し。
+
+        辞書のキーは PII を含まない前提で、値のみマスクする。
+
+        ネスト深度が `max_json_depth`（デフォルト 100）を超えた要素は
+        fail-closed で固定文字列 `"[fuseji: too deep]"` に置換される。
+        スタック消費や無限再帰由来の DoS を抑止する。
+
+        Example:
+            >>> from fuseji import Masker
+            >>> result = Masker().mask_json({"email": "a@b.com", "user": "山田"})
+            >>> result["email"]
+            '<EMAIL_1>'
+            >>> result["user"]
+            '山田'
+        """
+        return self._mask_value(data, depth=0)
+
+    def _mask_value(self, data: Any, *, depth: int) -> Any:
+        if depth > self._max_json_depth:
+            return _TOO_DEEP_PLACEHOLDER
+        if isinstance(data, str):
+            return self.mask(data).text
+        if isinstance(data, dict):
+            return {k: self._mask_value(v, depth=depth + 1) for k, v in data.items()}
+        if isinstance(data, list):
+            return [self._mask_value(v, depth=depth + 1) for v in data]
+        if isinstance(data, tuple):
+            return tuple(self._mask_value(v, depth=depth + 1) for v in data)
+        return data
+
+
+def _resolve_overlaps(entities: Sequence[Entity]) -> list[Entity]:
+    """オーバーラップするエンティティをスコア優先で解決する。
+
+    優先順位: スコア降順 → 長い span 優先 → 開始位置昇順。
+    採用済み span と重ならないものから順に採用し、最後に元テキスト位置順で
+    並べ直して返す。
+    """
+    ordered = sorted(entities, key=lambda e: (-e.score, -(e.end - e.start), e.start))
+    accepted: list[Entity] = []
+    spans: list[tuple[int, int]] = []
+    for e in ordered:
+        if any(not (e.end <= s or e.start >= ee) for s, ee in spans):
+            continue
+        accepted.append(e)
+        spans.append((e.start, e.end))
+    return sorted(accepted, key=lambda e: e.start)

fuseji/entity_types.py

@@ -0,0 +1,46 @@
+"""エンティティ種別の定数モジュール。
+
+ハードコードされた文字列リテラル（``"EMAIL"`` 等）の代わりに、
+タイプセーフな定数として利用できる。
+
+Example:
+    >>> from fuseji import InMemoryVault, entity_types
+    >>> vault = InMemoryVault(excluded_types=[entity_types.MY_NUMBER, entity_types.EMAIL])
+    >>> sorted(vault.excluded_types)
+    ['EMAIL', 'MY_NUMBER']
+
+定数は文字列そのもの（``str``）。Entity.type と直接比較できる。
+
+v0.2 以降で追加されるエンティティ種別（JP_ADDRESS、CORPORATE_NUMBER 等）も
+本モジュールに集約する予定。
+"""
+
+from __future__ import annotations
+
+#: メールアドレス
+EMAIL: str = "EMAIL"
+#: クレジットカード番号（Luhn 検証通過）
+CREDIT_CARD: str = "CREDIT_CARD"
+#: マイナンバー（個人番号 12 桁）
+MY_NUMBER: str = "MY_NUMBER"
+#: 日本の電話番号（携帯・固定・フリーダイヤル・ナビダイヤル）
+JP_PHONE_NUMBER: str = "JP_PHONE_NUMBER"
+#: 日本の郵便番号
+JP_POSTAL_CODE: str = "JP_POSTAL_CODE"
+#: 人名（GiNZA バックエンドが出力）
+PERSON: str = "PERSON"
+
+#: v0.1 で組み込み recognizers が出力する種別の全集合（NER 含む）
+V0_1_TYPES: frozenset[str] = frozenset(
+    {EMAIL, CREDIT_CARD, MY_NUMBER, JP_PHONE_NUMBER, JP_POSTAL_CODE, PERSON}
+)
+
+__all__ = [
+    "CREDIT_CARD",
+    "EMAIL",
+    "JP_PHONE_NUMBER",
+    "JP_POSTAL_CODE",
+    "MY_NUMBER",
+    "PERSON",
+    "V0_1_TYPES",
+]

fuseji/exceptions.py

@@ -0,0 +1,32 @@
+"""fuseji 例外階層。
+
+利用側で `except FusejiError` だけ書けば fuseji 由来の例外を一括で
+キャッチでき、spaCy ロード失敗や FastAPI フレームワーク例外と区別できる。
+
+`InvalidEntityError` と `InvalidConfigError` は `FusejiError` 階層に属しつつ
+`ValueError` も継承する多重継承で、既存の `except ValueError` も従来通り
+拾える非破壊的設計。
+"""
+
+from __future__ import annotations
+
+
+class FusejiError(Exception):
+    """fuseji が発生させる例外の基底クラス。
+
+    `except FusejiError` で fuseji 由来の例外のみをキャッチできる。
+    """
+
+
+class InvalidEntityError(FusejiError, ValueError):
+    """Entity の構築時にフィールドが不正な場合の例外。
+
+    既存コードとの互換性のため `ValueError` も多重継承している。
+    """
+
+
+class InvalidConfigError(FusejiError, ValueError):
+    """戦略・Vault・Masker 等の設定が不正な場合の例外。
+
+    既存コードとの互換性のため `ValueError` も多重継承している。
+    """

fuseji/integrations/__init__.py

@@ -0,0 +1,5 @@
+"""外部サービス連携サブパッケージ."""
+
+from .langfuse import make_mask_fn
+
+__all__ = ["make_mask_fn"]

fuseji/integrations/langfuse.py

@@ -0,0 +1,76 @@
+"""Langfuse SDK の mask フック用アダプター."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Callable
+from typing import Any
+
+from ..engine import Masker
+
+logger = logging.getLogger(__name__)
+
+# 例外時に返す fail-closed なプレースホルダー
+_FAIL_PLACEHOLDER = "[fuseji: masking failed]"
+
+# 環境変数で「フルトレースバックをログに出すか」を切り替える。デフォルトは
+# off で、例外型名のみログする（PII を含むトレースバックを残さないため）。
+# デバッグ目的で詳細が必要なときは FUSEJI_LANGFUSE_LOG_TRACEBACK=1 を設定する。
+_LOG_TRACEBACK_ENV = "FUSEJI_LANGFUSE_LOG_TRACEBACK"
+
+
+def _should_log_traceback() -> bool:
+    return os.environ.get(_LOG_TRACEBACK_ENV, "0") == "1"
+
+
+def make_mask_fn(masker: Masker | None = None) -> Callable[[Any], Any]:
+    """Langfuse SDK の ``mask`` パラメータに渡せるマスキング関数を生成する。
+
+    Args:
+        masker: 使用する Masker インスタンス。``None`` のとき新規に
+            ``Masker()`` を作る（v0.1 デフォルト認識器セット + Placeholder 戦略）。
+
+    Returns:
+        Langfuse SDK の ``mask=`` に渡せる callable。任意のデータ構造
+        （str / dict / list / tuple 等）を受け取り、マスク済みの同型
+        データを返す。
+
+    例外ハンドリング:
+        マスキング処理が例外で失敗した場合は fail-closed の方針で
+        ``"[fuseji: masking failed]"`` 文字列を返す。PII 漏洩を避けるため
+        原データはそのまま返さない。
+
+        ログ出力は **デフォルトで例外型名のみ**（トレースバックなし）。
+        トレースバックには元の PII を含む文字列が含まれる可能性があるため、
+        ログ集約基盤への漏洩を防ぐ。デバッグ目的で完全なトレースバックが
+        必要な場合は環境変数 ``FUSEJI_LANGFUSE_LOG_TRACEBACK=1`` を設定する。
+
+    Example:
+        Langfuse SDK と統合:
+
+        >>> from langfuse import Langfuse  # doctest: +SKIP
+        >>> from fuseji.integrations.langfuse import make_mask_fn
+        >>> langfuse = Langfuse(mask=make_mask_fn())  # doctest: +SKIP
+
+        スタンドアロンで動作確認:
+
+        >>> from fuseji.integrations.langfuse import make_mask_fn
+        >>> fn = make_mask_fn()
+        >>> "<EMAIL_1>" in fn({"data": "メール a@b.com"})["data"]
+        True
+    """
+    actual_masker: Masker = masker if masker is not None else Masker()
+
+    def _mask(data: Any) -> Any:
+        try:
+            return actual_masker.mask_json(data)
+        except Exception as e:
+            if _should_log_traceback():
+                logger.exception("fuseji: マスキング処理が例外で失敗")
+            else:
+                # デフォルト: 例外型のみログ。トレースバック内の PII 漏洩を防ぐ。
+                logger.warning("fuseji: マスキング処理が例外で失敗 (%s)", type(e).__name__)
+            return _FAIL_PLACEHOLDER
+
+    return _mask

fuseji/ner/__init__.py

@@ -0,0 +1,5 @@
+"""NER バックエンドサブパッケージ."""
+
+from .base import NerBackend
+
+__all__ = ["NerBackend"]

fuseji/ner/base.py

@@ -0,0 +1,19 @@
+"""NER バックエンドのプロトコル定義."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Protocol
+
+from ..types import Entity
+
+
+class NerBackend(Protocol):
+    """NER バックエンドのプロトコル。
+
+    認識器（regex/checksum）が拾えない、文中の自然な名詞句（人名・地名・組織名等）を
+    機械学習モデルで検出するためのインタフェース。Recognizer プロトコルと互換だが、
+    モデル依存のため optional extra として分離する。
+    """
+
+    def analyze(self, text: str) -> Iterable[Entity]: ...

fuseji/ner/ginza.py

@@ -0,0 +1,70 @@
+"""GiNZA バックエンド（PERSON 検出）."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from ..entity_types import PERSON
+from ..types import Entity
+
+if TYPE_CHECKING:
+    from spacy.language import Language
+
+# GiNZA は OntoNotes ではなく GSK 風の独自ラベルを返す。
+# v0.1 では「Person」だけを採用し、他のラベル（Title_Other, Province 等）は
+# 利用側で明示的に指定したいときのみ拾う。
+_DEFAULT_LABELS: tuple[str, ...] = ("Person",)
+
+
+class GinzaBackend:
+    """GiNZA (spaCy + ja_ginza) ベースの NER バックエンド。
+
+    `labels` で抽出する GiNZA ラベルを指定する。デフォルトは ``("Person",)``。
+    抽出した Entity の type フィールドは ``Person`` を慣用名 ``PERSON`` に
+    マップし、その他のラベルは大文字化してそのまま使う。
+
+    `[ginza]` extra 経由でのみインストール可能（``pip install fuseji[ginza]``）。
+    """
+
+    def __init__(
+        self,
+        labels: Iterable[str] | None = None,
+        model_name: str = "ja_ginza",
+        score: float = 0.85,
+    ) -> None:
+        try:
+            import spacy
+        except ImportError as e:
+            msg = (
+                "GinzaBackend を使うには spaCy と ja_ginza が必要です。"
+                "`pip install fuseji[ginza]` でインストールしてください。"
+            )
+            raise ImportError(msg) from e
+
+        self._labels: set[str] = set(labels) if labels is not None else set(_DEFAULT_LABELS)
+        self._score = score
+        # GiNZA 5.2 系の compound_splitter は新版 spaCy で設定不整合を起こすため除外
+        self._nlp: Language = spacy.load(model_name, exclude=["compound_splitter"])
+
+    @property
+    def labels(self) -> frozenset[str]:
+        return frozenset(self._labels)
+
+    def analyze(self, text: str) -> Iterable[Entity]:
+        if not text:
+            return
+        doc = self._nlp(text)
+        for ent in doc.ents:
+            if ent.label_ not in self._labels:
+                continue
+            # GiNZA の "Person" → 慣用名 PERSON 定数に正規化
+            type_ = PERSON if ent.label_ == "Person" else ent.label_.upper()
+            yield Entity(
+                type=type_,
+                text=ent.text,
+                start=ent.start_char,
+                end=ent.end_char,
+                score=self._score,
+                recognizer="ginza",
+            )

fuseji/recognizers/__init__.py

@@ -0,0 +1,17 @@
+"""PII 認識器サブパッケージ."""
+
+from .base import (
+    Recognizer,
+    default_recognizers,
+    normalize,
+    normalize_digits,
+    normalize_hyphens,
+)
+
+__all__ = [
+    "Recognizer",
+    "default_recognizers",
+    "normalize",
+    "normalize_digits",
+    "normalize_hyphens",
+]

fuseji/recognizers/base.py

@@ -0,0 +1,117 @@
+"""Recognizer プロトコルと共通の正規化・ヘルパユーティリティ."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from typing import Protocol
+
+from ..types import Entity
+
+# 認識器間で共有するセパレーターパターン（ハイフン/空白）。各認識器が
+# digits-only に正規化する際に使う。
+SEPARATOR_PATTERN: re.Pattern[str] = re.compile(r"[-\s]")
+
+
+class Recognizer(Protocol):
+    """PII 認識器のプロトコル。
+
+    属性:
+        entity_type: 認識する種別名（例: ``"EMAIL"``, ``"JP_PHONE_NUMBER"``）
+
+    メソッド:
+        analyze: テキストを走査し検出した `Entity` を返す。
+    """
+
+    entity_type: str
+
+    def analyze(self, text: str) -> Iterable[Entity]: ...
+
+
+# --- 文字正規化テーブル ---
+# いずれも 1 文字 ↔ 1 文字。codepoint 長が変わらないため、
+# 正規化後オフセットは元テキストに対して維持される。
+
+_DIGIT_TRANSLATION = str.maketrans("０１２３４５６７８９", "0123456789")
+
+_HYPHEN_TRANSLATION = str.maketrans(
+    {
+        "‐": "-",  # U+2010 HYPHEN
+        "‑": "-",  # U+2011 NON-BREAKING HYPHEN
+        "‒": "-",  # U+2012 FIGURE DASH
+        "–": "-",  # U+2013 EN DASH
+        "—": "-",  # U+2014 EM DASH
+        "―": "-",  # U+2015 HORIZONTAL BAR
+        "−": "-",  # U+2212 MINUS SIGN
+        "ー": "-",  # U+30FC KATAKANA-HIRAGANA PROLONGED SOUND MARK
+        "－": "-",  # U+FF0D FULLWIDTH HYPHEN-MINUS
+    }
+)
+
+# normalize() 用に digits + hyphens を 1 つの translate テーブルへマージ。
+# 両者のキーは disjoint（数字と記号）なので衝突なし。値は数字側が int、
+# ハイフン側が str（str.translate はどちらも受ける）。
+_NORMALIZE_TRANSLATION: dict[int, str | int] = {
+    **_DIGIT_TRANSLATION,
+    **_HYPHEN_TRANSLATION,
+}
+
+
+def normalize_digits(text: str) -> str:
+    """全角数字（０-９）を半角に変換。文字数は維持される。"""
+    return text.translate(_DIGIT_TRANSLATION)
+
+
+def normalize_hyphens(text: str) -> str:
+    """各種ハイフン類を ASCII ハイフン `-` に変換。文字数は維持される。
+
+    含まれる: U+2010 HYPHEN, U+2011 NON-BREAKING HYPHEN, U+2012 FIGURE DASH,
+    U+2013 EN DASH, U+2014 EM DASH, U+2015 HORIZONTAL BAR, U+2212 MINUS SIGN,
+    U+30FC KATAKANA-HIRAGANA PROLONGED SOUND MARK, U+FF0D FULLWIDTH HYPHEN-MINUS。
+    """
+    return text.translate(_HYPHEN_TRANSLATION)
+
+
+def normalize(text: str) -> str:
+    """数字とハイフンの両方を 1 パスで正規化。"""
+    return text.translate(_NORMALIZE_TRANSLATION)
+
+
+def has_digit_boundary(text: str, start: int, end: int) -> bool:
+    """マッチ位置 [start, end) の直前または直後が数字なら True を返す。
+
+    認識器がマッチ範囲を別 ID（より長い番号列）の一部と切り分けるためのヘルパ。
+    True を返した場合、その候補は除外すべき。
+
+    Args:
+        text: 正規化後のテキスト（半角数字に統一されている前提）。
+        start: マッチ開始位置（包含）。
+        end: マッチ終端位置（除外）。
+    """
+    if start > 0 and text[start - 1].isdigit():
+        return True
+    if end < len(text) and text[end].isdigit():  # noqa: SIM103
+        return True
+    return False
+
+
+def default_recognizers() -> tuple[Recognizer, ...]:
+    """v0.1 のデフォルト認識器セット。
+
+    EMAIL, CREDIT_CARD, MY_NUMBER, JP_PHONE_NUMBER, JP_POSTAL_CODE の順で返す。
+    順序は Masker エンジン側のオーバーラップ解決には影響しない（スコア優先）。
+    """
+    # 循環インポート回避のため遅延 import
+    from .credit_card import CreditCardRecognizer
+    from .email import EmailRecognizer
+    from .jp_phone import JpPhoneRecognizer
+    from .jp_postal import JpPostalRecognizer
+    from .my_number import MyNumberRecognizer
+
+    return (
+        EmailRecognizer(),
+        CreditCardRecognizer(),
+        MyNumberRecognizer(),
+        JpPhoneRecognizer(),
+        JpPostalRecognizer(),
+    )

fuseji/recognizers/credit_card.py

@@ -0,0 +1,55 @@
+"""クレジットカード認識器（Luhn チェック付き）."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from ..entity_types import CREDIT_CARD
+from ..types import Entity
+from .base import SEPARATOR_PATTERN, normalize
+
+# 13-19 桁の数字、間に任意のハイフン or 空白を許容
+_CC_PATTERN = re.compile(r"\d(?:[-\s]?\d){12,18}")
+
+
+def _luhn(digits: str) -> bool:
+    """Luhn チェックディジット検証。digits は数字のみ。"""
+    total = 0
+    for i, ch in enumerate(reversed(digits)):
+        d = int(ch)
+        if i % 2 == 1:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    return total % 10 == 0
+
+
+class CreditCardRecognizer:
+    """クレジットカード番号認識器。
+
+    13-19 桁の数字列（ハイフン/空白セパレーター可、全角数字・全角ハイフンも対応）を
+    候補とし、Luhn 検証に通過したもののみ Entity として返す。
+    Luhn 失敗は credit card ではないことが確実なので除外する（偽陽性抑制）。
+    """
+
+    entity_type = CREDIT_CARD
+
+    def analyze(self, text: str) -> Iterable[Entity]:
+        # 全角数字・全角ハイフンを正規化（1 文字 ↔ 1 文字なのでオフセット維持）
+        normalized = normalize(text)
+        for m in _CC_PATTERN.finditer(normalized):
+            digits = SEPARATOR_PATTERN.sub("", m.group())
+            if not 13 <= len(digits) <= 19:
+                continue
+            if not _luhn(digits):
+                continue
+            yield Entity(
+                type=self.entity_type,
+                text=text[m.start() : m.end()],  # 元テキストの表層を返す
+                start=m.start(),
+                end=m.end(),
+                score=0.95,
+                recognizer="credit_card",
+            )