feat(access-control-prover): 11.1 entry-recognition strategy registry

src/openultrasast/mapping/__init__.py

@@ -0,0 +1,5 @@
+"""Entry-point mapping package: legacy recognisers plus the strategy registry."""
+
+from .legacy import *  # noqa: F401,F403
+from .legacy import _php_methods as _php_methods  # re-exported internal helpers (enforcement adapter)
+from .legacy import _php_routes as _php_routes

src/openultrasast/mapping/registry.py

@@ -0,0 +1,52 @@
+"""Entry-recognition strategy registry (task 11.1, Reqs 1.1, 1.5, 1.7).
+
+Target knowledge enters entry recognition through registered strategies; the
+registry stamps every returned record with the strategy identifier unless the
+strategy recorded its own provenance. The registry itself names no target.
+"""
+
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .legacy import EntryPointRecord
+
+__all__ = ["EntryRecogniser", "register", "registry_entries", "registered_strategies"]
+
+
+@runtime_checkable
+class EntryRecogniser(Protocol):
+    """A target-specific entry-recognition strategy registered from data or a strategy module."""
+
+    identifier: str
+    languages: tuple[str, ...]
+
+    def recognize(self, target: Any, text: str) -> list["EntryPointRecord"]:
+        """Return the entry points this strategy recognises in one file."""
+        ...
+
+
+_STRATEGIES: dict[str, EntryRecogniser] = {}
+
+
+def register(recogniser: EntryRecogniser) -> None:
+    """Register a strategy; re-registering an identifier replaces the earlier strategy."""
+    _STRATEGIES[recogniser.identifier] = recogniser
+
+
+def registered_strategies(language: str) -> tuple[EntryRecogniser, ...]:
+    """Return the strategies that recognise entries for one language, ordered by identifier."""
+    return tuple(
+        strategy for strategy in sorted(_STRATEGIES.values(), key=lambda strategy: strategy.identifier) if language in strategy.languages
+    )
+
+
+def registry_entries(target: Any, text: str) -> list["EntryPointRecord"]:
+    """Run every matching strategy and stamp its identifier onto each returned record."""
+    records: list[EntryPointRecord] = []
+    for strategy in registered_strategies(getattr(target, "language", "")):
+        for record in strategy.recognize(target, text):
+            if record.provenance == "":
+                record = replace(record, provenance=f"strategy:{strategy.identifier}")
+            records.append(record)
+    return records