borderlint 0.2.0__py3-none-any.whl

borderlint/__init__.py

@@ -0,0 +1,3 @@
+"""borderlint — map and govern where your AI data and traffic flow."""
+
+__version__ = "0.2.0"

borderlint/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

borderlint/cli.py

@@ -0,0 +1,52 @@
+"""borderlint command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import report
+from .detect import scan
+from .kb import load_kb
+from .policy import Finding, evaluate, load_policy
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="borderlint", description="Map and govern where your AI data flows.")
+    sub = ap.add_subparsers(dest="cmd")
+    s = sub.add_parser("scan", help="Scan a path for AI data flows and check a residency policy.")
+    s.add_argument("path", nargs="?", default=".")
+    s.add_argument("-p", "--policy", help="residency policy JSON (omit for inventory mode)")
+    s.add_argument("-c", "--classification", help="data class on the scanned path (required with --policy)")
+    s.add_argument("-f", "--format", choices=["text", "json", "mermaid"], default="text")
+    s.add_argument("--providers", help="custom provider knowledge base JSON")
+    a = ap.parse_args(argv)
+
+    if a.cmd != "scan":
+        ap.print_help()
+        return 0
+
+    kb = load_kb(a.providers)
+    detections = scan(a.path, kb)
+
+    policy = None
+    if a.policy:
+        if not a.classification:
+            print("error: --classification is required when --policy is given", file=sys.stderr)
+            return 2
+        policy = load_policy(a.policy)
+        try:
+            findings = evaluate(detections, policy, a.classification, kb)
+        except KeyError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 2
+    else:
+        findings = [Finding(d, "ok", []) for d in detections]  # inventory mode
+
+    renderers = {"text": report.text, "json": report.as_json, "mermaid": report.mermaid}
+    print(renderers[a.format](findings, kb, policy))
+    return 1 if any(f.severity == "fail" for f in findings) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

borderlint/data/providers.json

@@ -0,0 +1,23 @@
+{
+  "providers": [
+    {"id": "openai", "name": "OpenAI", "sdks": ["openai"], "npm": ["openai", "@ai-sdk/openai"], "endpoints": ["api.openai.com"], "jurisdiction": "us"},
+    {"id": "anthropic", "name": "Anthropic", "sdks": ["anthropic"], "npm": ["@anthropic-ai/sdk", "@ai-sdk/anthropic"], "endpoints": ["api.anthropic.com"], "jurisdiction": "us"},
+    {"id": "google_gemini", "name": "Google Gemini", "sdks": ["google.generativeai", "google.genai"], "npm": ["@google/generative-ai", "@google/genai", "@ai-sdk/google", "@ai-sdk/google-vertex"], "endpoints": ["generativelanguage.googleapis.com"], "jurisdiction": "us"},
+    {"id": "azure_openai", "name": "Azure OpenAI", "sdks": [], "npm": ["@azure/openai", "@ai-sdk/azure"], "endpoints": ["openai.azure.com", "api.cognitive.microsoft.com", "inference.ai.azure.com"], "jurisdiction": "unknown", "region_scheme": "azure", "note": "regional hosts (<region>.api.cognitive.microsoft.com, *.<region>.inference.ai.azure.com) resolve; the standard openai.azure.com does not carry a region"},
+    {"id": "aws_bedrock", "name": "AWS Bedrock", "sdks": [], "npm": ["@aws-sdk/client-bedrock-runtime", "@ai-sdk/amazon-bedrock"], "endpoints": ["bedrock-runtime"], "jurisdiction": "unknown", "region_scheme": "aws", "note": "region is in the host: bedrock-runtime.<region>.amazonaws.com"},
+    {"id": "mistral", "name": "Mistral AI", "sdks": ["mistralai"], "npm": ["@mistralai/mistralai", "@ai-sdk/mistral"], "endpoints": ["api.mistral.ai"], "jurisdiction": "eu"},
+    {"id": "cohere", "name": "Cohere", "sdks": ["cohere"], "npm": ["cohere-ai", "@ai-sdk/cohere"], "endpoints": ["api.cohere.com", "api.cohere.ai"], "jurisdiction": "us"},
+    {"id": "deepseek", "name": "DeepSeek", "sdks": [], "npm": ["@ai-sdk/deepseek"], "endpoints": ["api.deepseek.com"], "jurisdiction": "cn"},
+    {"id": "tencent_hunyuan", "name": "Tencent Hunyuan", "sdks": ["tencentcloud"], "npm": [], "endpoints": ["hunyuan.tencentcloudapi.com"], "jurisdiction": "cn"},
+    {"id": "alibaba_dashscope", "name": "Alibaba DashScope", "sdks": ["dashscope"], "npm": [], "endpoints": ["dashscope-intl.aliyuncs.com", "dashscope.aliyuncs.com"], "jurisdiction": "cn", "endpoint_jurisdictions": {"dashscope-intl.aliyuncs.com": "sg"}},
+    {"id": "moonshot", "name": "Moonshot (Kimi)", "sdks": [], "npm": [], "endpoints": ["api.moonshot.cn"], "jurisdiction": "cn"},
+    {"id": "zhipu", "name": "Zhipu GLM", "sdks": ["zhipuai"], "npm": [], "endpoints": ["open.bigmodel.cn"], "jurisdiction": "cn"},
+    {"id": "baidu_ernie", "name": "Baidu ERNIE", "sdks": [], "npm": [], "endpoints": ["aip.baidubce.com"], "jurisdiction": "cn"},
+
+    {"id": "litellm", "name": "LiteLLM (router)", "kind": "aggregator", "sdks": ["litellm"], "npm": [], "endpoints": [], "jurisdiction": "unknown", "note": "multi-provider router; destination chosen at runtime"},
+    {"id": "langchain", "name": "LangChain (router)", "kind": "aggregator", "sdks": ["langchain", "langchain_openai", "langchain_anthropic", "langchain_community", "langchain_google_genai", "langchain_aws", "langchain_mistralai"], "npm": ["langchain", "@langchain/openai", "@langchain/anthropic", "@langchain/community", "@langchain/google-genai", "@langchain/aws", "@langchain/mistralai"], "endpoints": [], "jurisdiction": "unknown", "note": "multi-provider router; destination chosen at runtime"},
+    {"id": "llama_index", "name": "LlamaIndex (router)", "kind": "aggregator", "sdks": ["llama_index"], "npm": ["llamaindex"], "endpoints": [], "jurisdiction": "unknown", "note": "multi-provider router; destination chosen at runtime"},
+    {"id": "aisuite", "name": "aisuite (router)", "kind": "aggregator", "sdks": ["aisuite"], "npm": ["aisuite"], "endpoints": [], "jurisdiction": "unknown", "note": "multi-provider router; destination chosen at runtime"},
+    {"id": "vercel_ai", "name": "Vercel AI SDK (router)", "kind": "aggregator", "sdks": [], "npm": ["ai"], "endpoints": [], "jurisdiction": "unknown", "note": "provider-agnostic core; the @ai-sdk/<provider> adapter package determines the provider"}
+  ]
+}

borderlint/detect.py

@@ -0,0 +1,105 @@
+"""Scan a path for AI provider usage (SDK imports + endpoint references)."""
+
+from __future__ import annotations
+
+import ast
+import re
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+
+IGNORE = {".git", "node_modules", "__pycache__", ".venv", "venv", "build", "dist",
+          ".mypy_cache", ".pytest_cache", ".tox", ".ruff_cache"}
+TEXT_EXT = {".env", ".ts", ".tsx", ".js", ".jsx", ".yaml", ".yml", ".toml", ".json", ".ini", ".cfg", ".sh"}
+JS_EXT = {".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"}
+
+# Capture the module specifier from: `import X from "pkg"`, `import "pkg"`, `export ... from "pkg"`,
+# `require("pkg")`, dynamic `import("pkg")`. Regex over tree-sitter keeps borderlint zero-dependency.
+_JS_IMPORT = re.compile(
+    r'''(?:^[ \t]*import\b[^'"\n]*?\bfrom[ \t]*|^[ \t]*import[ \t]*|^[ \t]*export\b[^'"\n]*?\bfrom[ \t]*|\brequire[ \t]*\([ \t]*|\bimport[ \t]*\([ \t]*)['"]([^'"]+)['"]''',
+    re.M)
+
+
+@dataclass(frozen=True)
+class Detection:
+    provider_id: str
+    kind: str  # "sdk_import" | "endpoint_reference"
+    evidence: str
+    file: str
+    line: int
+    jurisdiction: str
+
+
+def _scan_py(path: str, src: str, kb) -> list[Detection]:
+    out: list[Detection] = []
+    try:
+        with warnings.catch_warnings():  # ponytail: hush the scanned file's own warnings, not ours
+            warnings.simplefilter("ignore")
+            tree = ast.parse(src)
+    except SyntaxError:
+        return out  # resilient: skip unparseable files
+    for n in ast.walk(tree):
+        if isinstance(n, ast.Import):
+            for a in n.names:
+                pid = kb.match_sdk(a.name)
+                if pid:
+                    out.append(Detection(pid, "sdk_import", a.name, path, n.lineno, kb.default_jurisdiction(pid)))
+        elif isinstance(n, ast.ImportFrom):
+            pid = kb.match_sdk(n.module or "")
+            if pid:
+                out.append(Detection(pid, "sdk_import", n.module, path, n.lineno, kb.default_jurisdiction(pid)))
+        elif isinstance(n, ast.Constant) and isinstance(n.value, str):
+            m = kb.match_endpoint(n.value)
+            if m:
+                out.append(Detection(m[0], "endpoint_reference", m[1], path, n.lineno, m[2]))
+    return out
+
+
+def _scan_text(path: str, src: str, kb) -> list[Detection]:
+    out: list[Detection] = []
+    for i, line in enumerate(src.splitlines(), 1):
+        m = kb.match_endpoint(line)
+        if m:
+            out.append(Detection(m[0], "endpoint_reference", m[1], path, i, m[2]))
+    return out
+
+
+def _scan_js(path: str, src: str, kb) -> list[Detection]:
+    out: list[Detection] = []
+    for m in _JS_IMPORT.finditer(src):
+        pid = kb.match_npm(m.group(1))
+        if pid:
+            line = src.count("\n", 0, m.start()) + 1
+            out.append(Detection(pid, "sdk_import", m.group(1), path, line, kb.default_jurisdiction(pid)))
+    return out
+
+
+def scan(root, kb) -> list[Detection]:
+    root = Path(root)
+    paths = [root] if root.is_file() else [p for p in root.rglob("*") if p.is_file()]
+    seen, out = set(), []
+    for p in paths:
+        if any(part in IGNORE for part in p.parts):
+            continue
+        suffix = p.suffix
+        is_py = suffix == ".py"
+        is_js = suffix in JS_EXT
+        is_text = suffix in TEXT_EXT or p.name == ".env"
+        if not (is_py or is_js or is_text):
+            continue
+        try:
+            src = p.read_text("utf-8", errors="ignore")
+        except OSError:
+            continue
+        if is_py:
+            dets = _scan_py(str(p), src, kb)
+        elif is_js:  # imports (new) + endpoint literals (existing text scan)
+            dets = _scan_js(str(p), src, kb) + _scan_text(str(p), src, kb)
+        else:
+            dets = _scan_text(str(p), src, kb)
+        for d in dets:
+            key = (d.provider_id, d.kind, d.evidence, d.file, d.line)
+            if key not in seen:
+                seen.add(key)
+                out.append(d)
+    return out

borderlint/kb.py

@@ -0,0 +1,105 @@
+"""Provider knowledge base: load and resolve a provider/endpoint to a jurisdiction."""
+
+from __future__ import annotations
+
+import json
+import re
+from importlib.resources import files
+
+# Region-coded endpoints (the host carries the region) → ccTLD jurisdiction.
+_AWS_RE = re.compile(r"\b([a-z]{2}(?:-gov)?-[a-z]+-\d)\b")
+_AWS_REGION = {
+    "ap-east-1": "hk", "ap-east-2": "hk", "cn-north-1": "cn", "cn-northwest-1": "cn",
+    "ap-southeast-1": "sg", "ap-southeast-2": "au", "ap-southeast-3": "id",
+    "ap-southeast-5": "my", "ap-southeast-7": "th", "ap-south-1": "in", "ap-south-2": "in",
+    "ap-northeast-1": "jp", "ap-northeast-2": "kr", "ap-northeast-3": "jp",
+    "eu-west-1": "ie", "eu-west-2": "gb", "eu-west-3": "fr", "eu-central-1": "de",
+    "eu-central-2": "ch", "eu-north-1": "se", "eu-south-1": "it", "eu-south-2": "es",
+    "me-south-1": "bh", "me-central-1": "ae", "af-south-1": "za", "il-central-1": "il",
+}
+_AZURE_RE = re.compile(
+    r"\b(eastus2?|westus[123]?|centralus|southcentralus|northcentralus|canadacentral|canadaeast|"
+    r"brazilsouth|northeurope|westeurope|uksouth|ukwest|francecentral|germanywestcentral|"
+    r"switzerlandnorth|swedencentral|norwayeast|polandcentral|italynorth|spaincentral|eastasia|"
+    r"southeastasia|japaneast|japanwest|koreacentral|australiaeast|australiasoutheast|centralindia|"
+    r"southindia|uaenorth|qatarcentral|southafricanorth|israelcentral|chinaeast2?|chinanorth[23]?)\b")
+_AZURE_REGION = {
+    "eastus": "us", "eastus2": "us", "westus": "us", "westus2": "us", "westus3": "us",
+    "centralus": "us", "southcentralus": "us", "northcentralus": "us", "canadacentral": "ca",
+    "canadaeast": "ca", "brazilsouth": "br", "northeurope": "ie", "westeurope": "nl",
+    "uksouth": "gb", "ukwest": "gb", "francecentral": "fr", "germanywestcentral": "de",
+    "switzerlandnorth": "ch", "swedencentral": "se", "norwayeast": "no", "polandcentral": "pl",
+    "italynorth": "it", "spaincentral": "es", "eastasia": "hk", "southeastasia": "sg",
+    "japaneast": "jp", "japanwest": "jp", "koreacentral": "kr", "australiaeast": "au",
+    "australiasoutheast": "au", "centralindia": "in", "southindia": "in", "uaenorth": "ae",
+    "qatarcentral": "qa", "southafricanorth": "za", "israelcentral": "il",
+    "chinaeast": "cn", "chinaeast2": "cn", "chinanorth": "cn", "chinanorth2": "cn", "chinanorth3": "cn",
+}
+
+
+def _region_jurisdiction(text: str, scheme: str):
+    if scheme == "aws":
+        m = _AWS_RE.search(text)
+        if not m:
+            return None
+        r = m.group(1)
+        return _AWS_REGION.get(r) or {"us": "us", "ca": "ca", "sa": "br", "cn": "cn"}.get(r.split("-")[0])
+    if scheme == "azure":
+        m = _AZURE_RE.search(text)
+        return _AZURE_REGION.get(m.group(1)) if m else None
+    return None
+
+
+def load_kb(path: str | None = None) -> "KB":
+    if path:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    else:
+        data = json.loads(files("borderlint").joinpath("data/providers.json").read_text("utf-8"))
+    return KB(data.get("providers", []))
+
+
+class KB:
+    def __init__(self, providers: list[dict]):
+        self.by_id = {p["id"]: p for p in providers}
+        sdks, npm, eps = [], [], []
+        for p in providers:
+            for s in p.get("sdks", []):
+                sdks.append((s, p["id"]))
+            for n in p.get("npm", []):
+                npm.append((n, p["id"]))
+            ej = p.get("endpoint_jurisdictions", {})
+            for h in p.get("endpoints", []):
+                eps.append((h, p["id"], ej.get(h, p.get("jurisdiction", "unknown"))))
+        # Longest match first so specific SDKs/hosts win over shorter ones.
+        self._sdks = sorted(sdks, key=lambda x: -len(x[0]))
+        self._npm = sorted(npm, key=lambda x: -len(x[0]))
+        self._eps = sorted(eps, key=lambda x: -len(x[0]))
+        self.region_scheme = {p["id"]: p["region_scheme"] for p in providers if p.get("region_scheme")}
+
+    def name(self, pid: str) -> str:
+        return self.by_id.get(pid, {}).get("name", pid)
+
+    def default_jurisdiction(self, pid: str) -> str:
+        return self.by_id.get(pid, {}).get("jurisdiction", "unknown")
+
+    def match_sdk(self, module: str) -> str | None:
+        for s, pid in self._sdks:
+            if module == s or module.startswith(s + "."):
+                return pid
+        return None
+
+    def match_npm(self, pkg: str) -> str | None:
+        for name, pid in self._npm:
+            if pkg == name or pkg.startswith(name + "/"):
+                return pid
+        return None
+
+    def match_endpoint(self, text: str):
+        for h, pid, juris in self._eps:
+            if h in text:
+                scheme = self.region_scheme.get(pid)
+                if scheme:
+                    juris = _region_jurisdiction(text, scheme) or juris
+                return pid, h, juris
+        return None

borderlint/policy.py

@@ -0,0 +1,61 @@
+"""Load a residency policy and evaluate detections (deny-by-default)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Finding:
+    detection: object
+    severity: str  # "ok" | "warn" | "fail"
+    reasons: list = field(default_factory=list)
+
+
+def load_policy(path: str) -> dict:
+    with open(path, encoding="utf-8") as fh:
+        data = json.load(fh)
+    # Shorthand: a bare {classification: [jurisdictions]} map is the classifications block.
+    if "classifications" not in data and data and all(isinstance(v, list) for v in data.values()):
+        data = {"classifications": data}
+    return data
+
+
+def _allowed(allow: list[str]) -> set[str]:
+    s = set(allow)
+    if "GBA" in s:  # GBA alias = hk + the nine Mainland GBA cities
+        s.update({"hk", "CN-GBA"})
+    return s
+
+
+def evaluate(detections, policy: dict, classification: str, kb=None) -> list[Finding]:
+    classes = policy.get("classifications", {})
+    if classification not in classes:
+        raise KeyError(f"classification '{classification}' not defined in policy")
+    allow = _allowed(classes[classification])
+    deny = set(policy.get("providers", {}).get("deny", []))
+    prov_allow = set(policy.get("providers", {}).get("allow", []))
+    on_unknown = policy.get("on_unknown", "warn")
+    fail_on = set(policy.get("fail_on", ["residency", "denied_provider"]))
+
+    findings = []
+    for d in detections:
+        reasons = []
+        if d.provider_id in deny or (prov_allow and d.provider_id not in prov_allow):
+            reasons.append("denied_provider")
+        if d.jurisdiction == "unknown":
+            reasons.append("unknown")
+        elif d.jurisdiction not in allow:
+            reasons.append("residency")
+        findings.append(Finding(d, _severity(reasons, fail_on, on_unknown), reasons))
+    return findings
+
+
+def _severity(reasons: list[str], fail_on: set[str], on_unknown: str) -> str:
+    if not reasons:
+        return "ok"
+    fail = (("denied_provider" in reasons and "denied_provider" in fail_on)
+            or ("residency" in reasons and "residency" in fail_on)
+            or ("unknown" in reasons and on_unknown == "fail"))
+    return "fail" if fail else "warn"

borderlint/report.py

@@ -0,0 +1,79 @@
+"""Render findings as text, JSON, or a Mermaid flow map (grouped by jurisdiction)."""
+
+from __future__ import annotations
+
+import json
+
+JURIS = {"us": "United States", "eu": "European Union", "cn": "Mainland China", "hk": "Hong Kong",
+         "sg": "Singapore", "gb": "United Kingdom", "mo": "Macao", "my": "Malaysia",
+         "CN-GBA": "Mainland GBA", "GBA": "Greater Bay Area", "unknown": "Unknown (region-dependent)"}
+REASON = {"denied_provider": "provider denied by policy",
+          "residency": "jurisdiction outside the allow-list for this data class",
+          "unknown": "jurisdiction could not be determined"}
+GBA_REF = ("GBA Standard Contract — https://www.digitalpolicy.gov.hk/en/our_work/"
+           "digital_infrastructure/mainland/gbacbdf/cross-boundary_data_flow/index.html")
+_RANK = {"ok": 0, "warn": 1, "fail": 2}
+
+
+def juris(j: str) -> str:
+    return JURIS.get(j, j)
+
+
+def _arrangements(findings, policy) -> list[str]:
+    regime = (policy or {}).get("home_regime")
+    flagged_china = any(f.severity != "ok" and f.detection.jurisdiction in ("cn", "CN-GBA") for f in findings)
+    if regime in ("pdpo", "pipl") and flagged_china:
+        return [f"Reference ({regime}): {GBA_REF}"]
+    return []
+
+
+def text(findings, kb, policy=None) -> str:
+    if not findings:
+        return "borderlint: no AI provider usage detected."
+    lines = ["borderlint — AI data-flow & residency report", "=" * 46]
+    by = {}
+    for f in findings:
+        by.setdefault(f.detection.provider_id, []).append(f)
+    for pid in sorted(by):
+        fs = by[pid]
+        worst = max((f.severity for f in fs), key=lambda s: _RANK[s])
+        mark = {"ok": " OK ", "warn": "WARN", "fail": "FAIL"}[worst]
+        js = ", ".join(juris(x) for x in sorted({f.detection.jurisdiction for f in fs}))
+        lines.append(f"[{mark}] {kb.name(pid)} -> {js}")
+        for f in fs:
+            d = f.detection
+            lines.append(f"        {d.file}:{d.line} ({d.kind}: {d.evidence})")
+            for r in f.reasons:
+                lines.append(f"           ! {REASON.get(r, r)}")
+    fails = sum(f.severity == "fail" for f in findings)
+    warns = sum(f.severity == "warn" for f in findings)
+    lines.append("")
+    lines += _arrangements(findings, policy)
+    lines.append(f"Summary: {fails} fail, {warns} warn, {len(findings) - fails - warns} ok")
+    return "\n".join(lines)
+
+
+def as_json(findings, kb, policy=None) -> str:
+    return json.dumps({
+        "findings": [{"provider": f.detection.provider_id, "name": kb.name(f.detection.provider_id),
+                      "jurisdiction": f.detection.jurisdiction, "severity": f.severity, "reasons": f.reasons,
+                      "kind": f.detection.kind, "evidence": f.detection.evidence,
+                      "file": f.detection.file, "line": f.detection.line} for f in findings],
+        "references": _arrangements(findings, policy),
+    }, indent=2)
+
+
+def mermaid(findings, kb, policy=None) -> str:
+    by_j = {}
+    for f in findings:
+        by_j.setdefault(f.detection.jurisdiction, set()).add(f.detection.provider_id)
+    lines = ["flowchart LR", "  app([Your application])"]
+    for j, pids in by_j.items():
+        jid = "j_" + j.replace("-", "_")
+        lines.append(f"  subgraph {jid}[{juris(j)}]")
+        for pid in sorted(pids):
+            lines.append(f"    {pid}[{kb.name(pid)}]")
+        lines.append("  end")
+        for pid in sorted(pids):
+            lines.append(f"  app --> {pid}")
+    return "\n".join(lines)

borderlint-0.2.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: borderlint
+Version: 0.2.0
+Summary: Map and govern where your AI data and traffic flow — east-west / APAC lens.
+Author: Iolaire McKinnon
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,compliance,data-residency,governance,llm,sovereignty
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# borderlint
+
+**Map and govern where your AI data and traffic flow — east-west / APAC lens.**
+
+A static, in-CI check for **HK / GBA entities**: does your AI data stay within the jurisdictions
+your PDPO / PIPL policy allows? borderlint statically scans your repo (**Python and
+TypeScript/JavaScript**) for AI provider usage, resolves each flow to a jurisdiction (ccTLD codes
+plus the `CN-GBA` / `GBA` tokens), and fails the build on any flow outside the allow-list for the
+data class you declare. Western and Chinese providers are treated evenly. **Zero runtime dependencies.**
+
+## Use
+
+```bash
+python -m borderlint scan ./service --policy residency.json --classification customer-pii
+```
+
+- No `--policy` → **inventory mode** (lists flows + jurisdictions, exits 0).
+- `--format json|mermaid` for machine output or a flow map.
+- Exit code is non-zero on a violation, so it gates CI.
+
+## Policy (the eval-set)
+
+`residency.json` maps each data class to the jurisdictions you accept:
+
+```json
+{
+  "home_regime": "pdpo",
+  "classifications": {
+    "customer-pii": ["hk", "CN-GBA", "sg"],
+    "employee-pii": ["hk", "CN-GBA"],
+    "non-pii":      ["hk", "CN-GBA", "cn", "mo", "sg", "us", "gb"]
+  }
+}
+```
+
+**Deny-by-default**: a flow to any code not on the list for the declared class fails — so `sg` is
+allowed but `my` is not, matching a PDPO agreed-locations EULA. `GBA` is shorthand for `hk` +
+`CN-GBA`. Cross-border arrangements (e.g. the GBA Standard Contract) are surfaced as reference
+links, never adjudicated.
+
+## Capabilities
+
+- **Languages:** Python (AST) and TypeScript/JavaScript (`import` / `require` / dynamic `import()`),
+  plus endpoint references in config/text files.
+- **Providers:** 13+ across the east-west boundary (OpenAI, Anthropic, Google, Azure, Bedrock,
+  Mistral, Cohere + Tencent, Alibaba, DeepSeek, Moonshot, Zhipu, Baidu), with Python and JS/TS
+  package names and the **Vercel AI SDK** (`@ai-sdk/*`).
+- **Aggregators:** litellm, langchain, LlamaIndex, aisuite, Vercel AI core (`ai`) → `unknown`
+  (runtime-routed), so `on_unknown: fail` blocks them for sensitive classes.
+- **Jurisdictions:** ccTLD/ISO codes + `CN-GBA` / `GBA`; **AWS/Azure region resolved from the
+  endpoint host** where present (e.g. `bedrock-runtime.ap-east-1…` → `hk`).
+- **Policy:** classification-keyed JSON eval-set, deny-by-default, provider allow/deny, configurable
+  failure set, declared home regime.
+- **Output & CI:** text / JSON / Mermaid, exit codes, GitHub Action + Jenkins.
+
+## Scope
+
+For HK / GBA home bases under PDPO / PIPL / GBA. Not yet: SARIF output, container/SCA mode, LLM
+enrichment, and dynamic / `base_url` endpoint resolution. Full roadmap in `CAPABILITIES.md`.
+
+## CI
+
+Same command in any pipeline. GitHub Actions (composite action):
+
+```yaml
+- uses: iolairus/borderlint@v0.2.0
+  with: { path: ., policy: residency.json, classification: customer-pii }
+```
+
+Jenkins / anything else: `pip install borderlint && borderlint scan . --policy residency.json --classification customer-pii` — a non-zero exit fails the stage. Full examples in `examples/ci/`.
+
+## License
+
+MIT © 2026 Iolaire McKinnon. Vendor-neutral by design.

borderlint-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+borderlint/__init__.py,sha256=ZYDwkT4abi5MhAa6LCVYCF2BQ4x56ye41e92S2EHluA,96
+borderlint/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+borderlint/cli.py,sha256=ngdFutjBo_g5tYp1t9veSLOBGegzcSUmv89mx4FWmGw,1856
+borderlint/detect.py,sha256=_YDxFeTwk7aci80HMObUKROnkpKxGhEzxJZq6uJiG7g,3943
+borderlint/kb.py,sha256=rMy2rL-5w0dbGZTu4qhrT6fh7evtacIvYxJ4czA_1CY,4865
+borderlint/policy.py,sha256=KFiXxmhe2gD0wx6P_lbNgIcVFnEeNQKM5-t-QtrPXjQ,2230
+borderlint/report.py,sha256=gwLZRMQBbqos2PfBvd-MURtYAtDfsbvTHOhal5C61eA,3491
+borderlint/data/providers.json,sha256=A1JL9nvP5jux2UPvmwltevU2--13wVroCFLmexvCi28,4050
+borderlint-0.2.0.dist-info/METADATA,sha256=6jV0tJrnI1Fj0xhXYgGimdF_uXsZeP0myBZOlM-xBA8,3561
+borderlint-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+borderlint-0.2.0.dist-info/entry_points.txt,sha256=MPBR-FwC2fgMOXIcPZZ8dkYu30p7jRzzJDdwnxskRqE,51
+borderlint-0.2.0.dist-info/licenses/LICENSE,sha256=feLNgoCutHpNXMNV5ZNI3KymqMNJ5XC3DJB_YOry6Dw,1073
+borderlint-0.2.0.dist-info/RECORD,,

borderlint-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

borderlint-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+borderlint = borderlint.cli:main

borderlint-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iolaire McKinnon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.