sourcelock 0.1.0__py3-none-any.whl

hc_source/__init__.py

@@ -0,0 +1,5 @@
+"""SourceLock: deterministic, provenance-tracked access to public healthcare data sources."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

hc_source/adapters/__init__.py

@@ -0,0 +1,500 @@
+"""Adapter discovery: built in, installed, and local.
+
+An adapter is a module-level ``ADAPTER``. SourceLock finds them in three places
+and treats all three identically once found:
+
+1. **built in** -- every module in this package. Drop a file here that defines
+   ``ADAPTER`` and it is discovered; there is no registry to edit, which is what
+   lets several people add routes at once without touching a shared file.
+2. **installed** -- any distribution advertising the ``sourcelock.adapters``
+   entry-point group. This is how you add a proprietary source without forking:
+   your licensed AMA CPT tables, your clearinghouse's payer list, your own
+   internal reference service. ``pip install`` it and ``hc-source tools`` shows
+   it beside the built-ins.
+3. **local** -- a directory of ``*.py`` files, for an adapter that belongs to one
+   repository and is not worth packaging. **Off unless you switch it on**, with
+   ``HC_SOURCE_LOCAL_ADAPTERS=1`` (meaning ``./.sourcelock/adapters``) or
+   ``HC_SOURCE_LOCAL_ADAPTERS=/path/you/trust``. Every file in that directory is
+   imported -- which is to say executed -- before anything about it has been
+   validated, so switching this on is a statement that you trust whoever can
+   write there. It defaulted to on, and combined with the ``pull_request``
+   trigger ``hc-source init --ci`` writes, that handed any pull request
+   arbitrary code execution on the runner. See :func:`local_adapter_dir`.
+
+Rules enforced at discovery, for all three:
+
+* the module defines ``ADAPTER = MyAdapter()`` (an entry point may also point
+  straight at the adapter object or at a zero-argument factory);
+* the adapter passes :func:`~hc_source.interfaces.validate_adapter` -- same
+  contract check, same ``extra='forbid'`` requirement, same canary rules;
+* every tool is invoked through :meth:`~hc_source.interfaces.ToolSpec.invoke`,
+  so the zero-PHI guard runs on a third-party route exactly as it does on
+  ``codes.valid_on``. There is no privileged path: an adapter you installed is
+  not more trusted than one we shipped, and neither is more trusted than the
+  guard;
+* a module whose name starts with ``_`` and defines no ``ADAPTER`` is treated as
+  a private helper and skipped silently; any other module without an ``ADAPTER``
+  is reported as a load error, because it is almost always a typo;
+* **a third-party adapter may not claim a built-in source id.** The built-in
+  wins and the newcomer is reported as a load error naming both. Shadowing
+  ``codes`` with something that answers differently would turn every receipt
+  that cites ``codes`` into a lie, and it would do it silently.
+
+A load failure is never a disappearance. Every error is collected as an
+:class:`AdapterLoadError` carrying where it came from, and ``tools``, ``call``,
+``doctor`` and the MCP server all surface it -- a source someone is paying for
+must not go quiet.
+
+Helper code shared between built-in adapters belongs in ``hc_source/``, not here.
+
+See ``ADAPTER_GUIDE.md`` and ``examples/sourcelock-example-adapter/``.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import os
+import pkgutil
+import sys
+from dataclasses import dataclass, field
+from importlib import metadata
+from pathlib import Path
+
+from ..interfaces import (
+    AdapterError,
+    Canary,
+    CanaryObservation,
+    SourceAdapter,
+    ToolResult,
+    ToolSpec,
+    validate_adapter,
+)
+
+__all__ = [
+    "AdapterError",
+    "AdapterLoadError",
+    "Canary",
+    "CanaryObservation",
+    "DiscoveryResult",
+    "ENTRY_POINT_GROUP",
+    "LOCAL_ADAPTER_DIR",
+    "LOCAL_ADAPTER_ENV",
+    "ORIGIN_BUILTIN",
+    "SourceAdapter",
+    "ToolResult",
+    "ToolSpec",
+    "discover",
+    "discover_adapters",
+    "discovery_errors",
+    "find_tool",
+    "get_adapter",
+    "iter_tools",
+    "local_adapter_dir",
+]
+
+ADAPTER_ATTR = "ADAPTER"
+
+#: Entry-point group a distribution advertises to add a source.
+ENTRY_POINT_GROUP = "sourcelock.adapters"
+
+#: Where a repository-local adapter lives, relative to the working directory.
+LOCAL_ADAPTER_DIR = ".sourcelock/adapters"
+
+#: Override the local directory, or turn it off with ``0``/``off``/``no``.
+LOCAL_ADAPTER_ENV = "HC_SOURCE_LOCAL_ADAPTERS"
+
+ORIGIN_BUILTIN = "builtin"
+
+#: Local files are executed under a namespace of their own so a file called
+#: ``codes.py`` cannot be imported later as ``hc_source.adapters.codes``.
+_LOCAL_MODULE_PREFIX = "sourcelock_local_adapters"
+
+_OFF = {"0", "off", "no", "false", "none", ""}
+_ON = {"1", "on", "yes", "true"}
+
+
+@dataclass(frozen=True)
+class AdapterLoadError:
+    """An adapter could not be loaded. Structured, so nothing vanishes quietly.
+
+    ``module`` names the thing that failed -- a dotted module for a built-in, an
+    ``entry-point`` label for an installed one, a path for a local file.
+    ``origin`` says which of the three discovery routes it came from, because
+    "the adapter I pip-installed is broken" and "the adapter you ship is broken"
+    are the same sentence otherwise. ``source_id`` is the id the failure cost
+    you, when it can be known without importing.
+    """
+
+    module: str
+    error: str
+    origin: str = ORIGIN_BUILTIN
+    source_id: str | None = None
+
+    def __str__(self) -> str:
+        where = "" if self.origin == ORIGIN_BUILTIN else f" [{self.origin}]"
+        return f"{self.module}{where}: {self.error}"
+
+    def as_dict(self) -> dict[str, str | None]:
+        return {
+            "module": self.module,
+            "error": self.error,
+            "origin": self.origin,
+            "source_id": self.source_id,
+        }
+
+
+@dataclass
+class DiscoveryResult:
+    adapters: list[SourceAdapter] = field(default_factory=list)
+    errors: list[AdapterLoadError] = field(default_factory=list)
+    #: source_id -> where it came from ("builtin", "entry-point:...", "local:...").
+    origins: dict[str, str] = field(default_factory=dict)
+
+    def origin(self, source_id: str) -> str:
+        return self.origins.get(source_id, ORIGIN_BUILTIN)
+
+    def third_party(self) -> list[SourceAdapter]:
+        return [a for a in self.adapters if self.origin(a.source_id) != ORIGIN_BUILTIN]
+
+
+# ---------------------------------------------------------------------------
+# discovery
+# ---------------------------------------------------------------------------
+
+
+def discover(*, strict: bool = False, reload: bool = False) -> DiscoveryResult:
+    """Import every adapter SourceLock can see, from all three routes.
+
+    A broken adapter is collected as an error rather than raised, so one bad
+    module does not hide the other routes. Pass ``strict=True`` to raise the
+    first error instead.
+
+    Order is fixed and matters: built-ins are claimed first, then entry points
+    sorted by name, then local files sorted by filename. Discovery is therefore
+    deterministic, and the first claimant of a source id keeps it.
+    """
+    result = DiscoveryResult()
+    _discover_builtin(result, strict=strict, reload=reload)
+    _discover_entry_points(result, strict=strict)
+    _discover_local(result, strict=strict)
+    result.adapters.sort(key=lambda a: a.source_id)
+    return result
+
+
+def _discover_builtin(result: DiscoveryResult, *, strict: bool, reload: bool) -> None:
+    for info in sorted(pkgutil.iter_modules(__path__), key=lambda m: m.name):
+        if info.ispkg or info.name.startswith("__"):
+            continue
+        module_name = f"{__name__}.{info.name}"
+        try:
+            module = importlib.import_module(module_name)
+            if reload:
+                module = importlib.reload(module)
+        except Exception as exc:  # noqa: BLE001 - report, never crash discovery
+            _record(
+                result,
+                AdapterLoadError(module_name, f"{type(exc).__name__}: {exc}", ORIGIN_BUILTIN),
+                strict,
+            )
+            continue
+
+        adapter = getattr(module, ADAPTER_ATTR, None)
+        if adapter is None:
+            if info.name.startswith("_"):
+                continue
+            _record(
+                result,
+                AdapterLoadError(
+                    module_name, f"defines no module-level {ADAPTER_ATTR}", ORIGIN_BUILTIN
+                ),
+                strict,
+            )
+            continue
+
+        _claim(result, adapter, module=module_name, origin=ORIGIN_BUILTIN, strict=strict)
+
+
+def _discover_entry_points(result: DiscoveryResult, *, strict: bool) -> None:
+    for entry in _entry_points():
+        label = f"{ENTRY_POINT_GROUP}:{entry.name}"
+        origin = f"entry-point:{_distribution_name(entry)}"
+        try:
+            loaded = entry.load()
+        except Exception as exc:  # noqa: BLE001
+            _record(
+                result,
+                AdapterLoadError(
+                    label, f"{type(exc).__name__}: {exc}", origin, source_id=entry.name
+                ),
+                strict,
+            )
+            continue
+
+        try:
+            adapter = _coerce(loaded, label)
+        except AdapterError as exc:
+            _record(result, AdapterLoadError(label, str(exc), origin, entry.name), strict)
+            continue
+
+        _claim(result, adapter, module=label, origin=origin, strict=strict, hint=entry.name)
+
+
+def _discover_local(result: DiscoveryResult, *, strict: bool) -> None:
+    directory = local_adapter_dir()
+    if directory is None or not directory.is_dir():
+        return
+    for path in sorted(directory.glob("*.py")):
+        if path.name.startswith("__"):
+            continue
+        label = str(path)
+        origin = f"local:{path}"
+        try:
+            module = _load_local_module(path)
+        except Exception as exc:  # noqa: BLE001
+            _record(
+                result,
+                AdapterLoadError(label, f"{type(exc).__name__}: {exc}", origin, path.stem),
+                strict,
+            )
+            continue
+
+        adapter = getattr(module, ADAPTER_ATTR, None)
+        if adapter is None:
+            if path.stem.startswith("_"):
+                continue
+            _record(
+                result,
+                AdapterLoadError(
+                    label, f"defines no module-level {ADAPTER_ATTR}", origin, path.stem
+                ),
+                strict,
+            )
+            continue
+
+        _claim(result, adapter, module=label, origin=origin, strict=strict, hint=path.stem)
+
+
+def local_adapter_dir() -> Path | None:
+    """The local adapter directory, or ``None`` -- which is the default.
+
+    **Unset means OFF.** Loading Python out of a directory is executing it, and
+    this used to default to ON at ``./.sourcelock/adapters``: every
+    non-underscore ``.py`` there was imported, before any contract check, as
+    part of ``tools``, ``call``, ``doctor`` and the MCP server. ``hc-source init
+    --ci`` writes a workflow with a ``pull_request`` trigger, so a pull request
+    that added ``.sourcelock/adapters/steal.py`` got arbitrary code execution
+    with the runner's token and network -- from a fork, with no review, on the
+    first CI run. "Your own repository" is not the trust level of a PR branch.
+
+    Opting in:
+
+    ============================================ =============================
+    unset, ``0``/``off``/``no``/``false``/``none`` off (the default)
+    ``1``/``on``/``yes``/``true``                  ``./.sourcelock/adapters``
+    anything else                                  that path, verbatim
+    ============================================ =============================
+
+    Whichever way you opt in, you are declaring that directory trusted to run
+    code in this process. Do not turn it on in a job that builds pull requests
+    from people who cannot already push to the repository.
+    """
+    raw = os.environ.get(LOCAL_ADAPTER_ENV)
+    if raw is None:
+        return None
+    value = raw.strip()
+    if value.lower() in _OFF:
+        return None
+    if value.lower() in _ON:
+        return Path(LOCAL_ADAPTER_DIR)
+    return Path(value)
+
+
+def _entry_points():
+    try:
+        found = metadata.entry_points(group=ENTRY_POINT_GROUP)
+    except Exception:  # noqa: BLE001 - a broken environment must not end discovery
+        return []
+    return sorted(found, key=lambda e: (e.name, e.value))
+
+
+def _distribution_name(entry) -> str:
+    """Which installed distribution advertised this entry point.
+
+    ``EntryPoint.dist`` is populated by ``entry_points()`` but not by an
+    EntryPoint someone constructed directly (which is how the tests inject one),
+    so fall back to the module the value names -- never to nothing, because the
+    whole point of the origin label is telling a customer which package to fix.
+    """
+    dist = getattr(entry, "dist", None)
+    name = getattr(dist, "name", None)
+    if not name and dist is not None:
+        meta = getattr(dist, "metadata", None)
+        name = meta.get("Name") if meta is not None else None
+    return name or entry.value.split(":", 1)[0].split(".", 1)[0]
+
+
+def _coerce(loaded, label: str) -> object:
+    """Accept the three shapes an entry point may point at.
+
+    A module with an ``ADAPTER``, the adapter object itself, or a zero-argument
+    factory. Anything else is a load error naming what we got, so a plugin
+    author reads a sentence instead of an ``AttributeError`` from our internals.
+    """
+    if isinstance(loaded, SourceAdapter):
+        return loaded
+    candidate = getattr(loaded, ADAPTER_ATTR, None)
+    if candidate is not None:
+        return candidate
+    if callable(loaded):
+        produced = loaded()
+        if produced is None:
+            raise AdapterError(f"{label}: the factory returned None")
+        return produced
+    raise AdapterError(
+        f"{label}: entry point resolved to {type(loaded).__name__}, which is neither a "
+        f"SourceAdapter, a module defining {ADAPTER_ATTR}, nor a factory returning one"
+    )
+
+
+def _load_local_module(path: Path):
+    """Execute a local adapter file under a namespace of its own."""
+    name = f"{_LOCAL_MODULE_PREFIX}.{path.stem}"
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"{path.name} is not loadable as a Python module")
+    module = importlib.util.module_from_spec(spec)
+    # Registered so pydantic can resolve the module's own annotations, but under
+    # `sourcelock_local_adapters.*` -- a local file called `codes.py` must never
+    # become importable as `hc_source.adapters.codes`.
+    sys.modules[name] = module
+    try:
+        spec.loader.exec_module(module)
+    except BaseException:
+        sys.modules.pop(name, None)
+        raise
+    return module
+
+
+def _claim(
+    result: DiscoveryResult,
+    adapter,
+    *,
+    module: str,
+    origin: str,
+    strict: bool,
+    hint: str | None = None,
+) -> None:
+    """Validate an adapter and give it its source id, or say who already has it."""
+    try:
+        validated = validate_adapter(adapter, origin=module)
+    except Exception as exc:  # noqa: BLE001
+        _record(
+            result,
+            AdapterLoadError(module, f"{type(exc).__name__}: {exc}", origin, hint),
+            strict,
+        )
+        return
+
+    source_id = validated.source_id
+    incumbent = result.origins.get(source_id)
+    if incumbent is not None:
+        _record(
+            result,
+            AdapterLoadError(
+                module,
+                (
+                    f"source_id {source_id!r} is already provided by {incumbent}. "
+                    "SourceLock will not let one adapter answer under another's name: "
+                    "every receipt naming this source would become ambiguous, and the "
+                    "ambiguity would be invisible. Give this adapter its own source_id "
+                    "(and its own tool prefix) instead."
+                ),
+                origin,
+                source_id,
+            ),
+            strict,
+        )
+        return
+
+    result.adapters.append(validated)
+    result.origins[source_id] = origin
+
+
+def _record(result: DiscoveryResult, error: AdapterLoadError, strict: bool) -> None:
+    if strict:
+        raise AdapterError(str(error))
+    result.errors.append(error)
+
+
+# ---------------------------------------------------------------------------
+# lookups
+# ---------------------------------------------------------------------------
+
+
+def discover_adapters(*, strict: bool = False) -> list[SourceAdapter]:
+    """Every valid adapter, sorted by source_id."""
+    return discover(strict=strict).adapters
+
+
+def discovery_errors() -> list[AdapterLoadError]:
+    """Every adapter that could not be loaded, from any of the three routes.
+
+    Exists because ``discover_adapters`` throws its errors away, and every
+    caller that used it -- ``tools``, ``call``, the MCP server -- therefore
+    reported a broken adapter as an adapter that simply is not there. Doctor was
+    the only command that knew the difference. A source someone is paying for
+    disappearing quietly is not an acceptable failure mode for a product whose
+    entire claim is that it tells you when something moved.
+    """
+    return discover().errors
+
+
+def _module_source_id(error: AdapterLoadError) -> str:
+    """The source id a failed adapter WOULD have provided.
+
+    A module that did not import has no ``source_id`` to ask. An entry point and
+    a local file carry the answer in their name; a built-in module carries it in
+    its basename, by the one-module-per-source rule.
+    """
+    if error.source_id:
+        return error.source_id
+    return error.module.rsplit(".", 1)[-1]
+
+
+def get_adapter(source_id: str) -> SourceAdapter:
+    found = discover()
+    for adapter in found.adapters:
+        if adapter.source_id == source_id:
+            return adapter
+    for error in found.errors:
+        if _module_source_id(error) == source_id:
+            raise AdapterError(
+                f"the {source_id!r} adapter exists but failed to load -- {error}. It is "
+                "broken, not absent; fix the module rather than removing the source."
+            )
+    raise KeyError(f"no adapter with source_id {source_id!r}")
+
+
+def iter_tools(adapters: list[SourceAdapter] | None = None) -> list[ToolSpec]:
+    """Every tool from every adapter, sorted by name."""
+    adapters = discover_adapters() if adapters is None else adapters
+    return sorted((t for a in adapters for t in a.tools()), key=lambda t: t.name)
+
+
+def find_tool(name: str, adapters: list[SourceAdapter] | None = None) -> ToolSpec:
+    for tool in iter_tools(adapters):
+        if tool.name == name:
+            return tool
+    if adapters is None:
+        # "No such tool" is the wrong answer when the module that provides it
+        # blew up on import: it sends the caller to check their spelling instead
+        # of their install.
+        wanted_source = name.split(".", 1)[0]
+        for error in discovery_errors():
+            if _module_source_id(error) == wanted_source:
+                raise AdapterError(
+                    f"the adapter that provides this tool failed to load -- {error}. The "
+                    "route is broken, not missing."
+                )
+    raise KeyError(f"no tool named {name!r}")