fact-kit 0.3.0a1__tar.gz

fact_kit-0.3.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Space
+
+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.

fact_kit-0.3.0a1/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: fact-kit
+Version: 0.3.0a1
+Summary: Reads the fact packages built by fact-kit
+Keywords: fact-kit,facts,semver
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Dist: orjson>=3.10
+Requires-Dist: semver>=3.0
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/carlos-space/fact-kit
+Project-URL: Issues, https://github.com/carlos-space/fact-kit/issues
+Description-Content-Type: text/markdown
+
+# fact-kit（Python）
+
+讀取 fact-kit 建出來的 `-facts` 套件。行為規格是倉庫裡的 `conformance/README.md`，五種語言的讀取實作共用同一份樣本。
+
+## 安裝
+
+```sh
+uv add fact-kit
+# 或
+pip install fact-kit
+```
+
+需要 Python 3.11 以上。依賴 `orjson`（讀 JSON）與 `semver`（比較版號）。PyPI 套件名是 `fact-kit`，匯入名是 `fact_kit`。
+
+## 用法
+
+```python
+from fact_kit import FactReadError, read_facts
+
+try:
+    reader = read_facts("demo-facts/sdk", root="/path/to/hub", version="0.50.0", platform="claude-code")
+except FactReadError as error:
+    print(error.code)  # not-an-index、unsupported-index-format、not-found 或 invalid-version
+    raise
+
+limit = reader.value("demo.limit")  # 取 content["value"]
+fact = reader.get("demo.limit")  # 整筆 fact，帶 content、since，有的話還有 stability
+for item in reader.facts:  # 這個讀者看得到的所有 fact，順序同 index
+    print(item["id"], item["since"])
+```
+
+`read_facts(spec, *, root=None, version=None, include=(), platform=None, os=None) -> FactReader`
+
+| 參數       | 說明                                                                   |
+| :--------- | :--------------------------------------------------------------------- |
+| `spec`     | `<套件>` 或 `<套件>/<路徑>`，套件名可以帶 scope                        |
+| `root`     | 從這個目錄開始找套件，預設是目前的工作目錄。工作目錄不固定時請明確傳入 |
+| `version`  | 讀者正在跑的版號，或 `"head"`。沒給時讀最新已發布的內容                |
+| `include`  | `head` 讀者額外要讀的 `pending` 標籤                                   |
+| `platform` | 讀者的平台，例如 `"claude-code"`                                       |
+| `os`       | `"macos"`、`"linux"` 或 `"windows"`                                    |
+
+`FactReader` 有 `package`、`version`（已安裝 fact 套件的版號）、`entry`、`describes`、`facts`、`has(id)`、`get(id)` 與 `value(id)`。`get` 找不到 id 時丟 `KeyError`，`value` 遇到沒有 `value` 的 content 時丟 `ValueError`。
+
+只想篩選已經讀進來的 index 時，用 `select_facts(index, *, version=None, include=(), platform=None, os=None) -> list[dict]`。`compare_versions(a, b)` 與 `release_line(version)` 是版號比較與發布線的公開函式。
+
+## 套件解析
+
+照 Node 的 `require.resolve` 規則，以 `root` 為起點：
+
+1. self-reference：最近的 `package.json` 名稱等於被讀的套件，而且有 `exports` 時，用它解析。
+2. 往上層找第一個有 `node_modules/<套件>` 的目錄，並跟著符號連結。
+3. `exports` 支援字串、陣列、條件物件（條件集合是 `node-addons`、`node`、`require`、`module-sync`、`default`，依寫的順序）、巢狀條件、`*` 萬用字元與 `null`。
+4. 沒有 `exports` 時，退回檔案路徑 `<套件目錄>/<路徑>/index.json`。檔案不存在時，往上一層的 `node_modules` 繼續找。
+
+已知差異：不讀 `NODE_PATH`，也不找全域資料夾。
+
+## 錯誤代碼
+
+所有錯誤都是 `FactReadError`（繼承 `Exception`），用 `.code` 判斷。訊息給人看，之後可能改。
+
+| `.code`                    | 何時                                                                              |
+| :------------------------- | :-------------------------------------------------------------------------------- |
+| `not-an-index`             | 檔案不是 JSON，頂層不是物件，`facts` 不是陣列，或 `package` 不是字串              |
+| `unsupported-index-format` | `indexFormat` 的 major 不是 1，或不是 `<數字>.<數字>` 的字串                      |
+| `not-found`                | 找不到套件，套件沒有 export 那個 `index.json`，檔案不存在，或 `spec` 的寫法不合格 |
+| `invalid-version`          | `version` 不是 `"head"` 也不是完整的 `X.Y.Z`，或 index 裡的 `since` 不是版號      |
+
+## 和 JS 版的差異
+
+- 不比對 `describes` 與已安裝產品的版本。`reader.describes` 會原樣回傳，但不會因為已安裝的產品比較新而丟錯，也不會用已安裝的版本當預設的 `version`。
+- 不提供 `onRead`。
+
+## 開發
+
+```sh
+cd py
+uv run pytest
+```
+
+測試讀倉庫的 `conformance/`。位置不在往上找得到的地方時，設環境變數 `FACT_KIT_CONFORMANCE`。讀自己 facts 的測試用 `FACT_KIT_FACTS` 指到 `facts/` 目錄。

fact_kit-0.3.0a1/README.md

@@ -0,0 +1,81 @@
+# fact-kit（Python）
+
+讀取 fact-kit 建出來的 `-facts` 套件。行為規格是倉庫裡的 `conformance/README.md`，五種語言的讀取實作共用同一份樣本。
+
+## 安裝
+
+```sh
+uv add fact-kit
+# 或
+pip install fact-kit
+```
+
+需要 Python 3.11 以上。依賴 `orjson`（讀 JSON）與 `semver`（比較版號）。PyPI 套件名是 `fact-kit`，匯入名是 `fact_kit`。
+
+## 用法
+
+```python
+from fact_kit import FactReadError, read_facts
+
+try:
+    reader = read_facts("demo-facts/sdk", root="/path/to/hub", version="0.50.0", platform="claude-code")
+except FactReadError as error:
+    print(error.code)  # not-an-index、unsupported-index-format、not-found 或 invalid-version
+    raise
+
+limit = reader.value("demo.limit")  # 取 content["value"]
+fact = reader.get("demo.limit")  # 整筆 fact，帶 content、since，有的話還有 stability
+for item in reader.facts:  # 這個讀者看得到的所有 fact，順序同 index
+    print(item["id"], item["since"])
+```
+
+`read_facts(spec, *, root=None, version=None, include=(), platform=None, os=None) -> FactReader`
+
+| 參數       | 說明                                                                   |
+| :--------- | :--------------------------------------------------------------------- |
+| `spec`     | `<套件>` 或 `<套件>/<路徑>`，套件名可以帶 scope                        |
+| `root`     | 從這個目錄開始找套件，預設是目前的工作目錄。工作目錄不固定時請明確傳入 |
+| `version`  | 讀者正在跑的版號，或 `"head"`。沒給時讀最新已發布的內容                |
+| `include`  | `head` 讀者額外要讀的 `pending` 標籤                                   |
+| `platform` | 讀者的平台，例如 `"claude-code"`                                       |
+| `os`       | `"macos"`、`"linux"` 或 `"windows"`                                    |
+
+`FactReader` 有 `package`、`version`（已安裝 fact 套件的版號）、`entry`、`describes`、`facts`、`has(id)`、`get(id)` 與 `value(id)`。`get` 找不到 id 時丟 `KeyError`，`value` 遇到沒有 `value` 的 content 時丟 `ValueError`。
+
+只想篩選已經讀進來的 index 時，用 `select_facts(index, *, version=None, include=(), platform=None, os=None) -> list[dict]`。`compare_versions(a, b)` 與 `release_line(version)` 是版號比較與發布線的公開函式。
+
+## 套件解析
+
+照 Node 的 `require.resolve` 規則，以 `root` 為起點：
+
+1. self-reference：最近的 `package.json` 名稱等於被讀的套件，而且有 `exports` 時，用它解析。
+2. 往上層找第一個有 `node_modules/<套件>` 的目錄，並跟著符號連結。
+3. `exports` 支援字串、陣列、條件物件（條件集合是 `node-addons`、`node`、`require`、`module-sync`、`default`，依寫的順序）、巢狀條件、`*` 萬用字元與 `null`。
+4. 沒有 `exports` 時，退回檔案路徑 `<套件目錄>/<路徑>/index.json`。檔案不存在時，往上一層的 `node_modules` 繼續找。
+
+已知差異：不讀 `NODE_PATH`，也不找全域資料夾。
+
+## 錯誤代碼
+
+所有錯誤都是 `FactReadError`（繼承 `Exception`），用 `.code` 判斷。訊息給人看，之後可能改。
+
+| `.code`                    | 何時                                                                              |
+| :------------------------- | :-------------------------------------------------------------------------------- |
+| `not-an-index`             | 檔案不是 JSON，頂層不是物件，`facts` 不是陣列，或 `package` 不是字串              |
+| `unsupported-index-format` | `indexFormat` 的 major 不是 1，或不是 `<數字>.<數字>` 的字串                      |
+| `not-found`                | 找不到套件，套件沒有 export 那個 `index.json`，檔案不存在，或 `spec` 的寫法不合格 |
+| `invalid-version`          | `version` 不是 `"head"` 也不是完整的 `X.Y.Z`，或 index 裡的 `since` 不是版號      |
+
+## 和 JS 版的差異
+
+- 不比對 `describes` 與已安裝產品的版本。`reader.describes` 會原樣回傳，但不會因為已安裝的產品比較新而丟錯，也不會用已安裝的版本當預設的 `version`。
+- 不提供 `onRead`。
+
+## 開發
+
+```sh
+cd py
+uv run pytest
+```
+
+測試讀倉庫的 `conformance/`。位置不在往上找得到的地方時，設環境變數 `FACT_KIT_CONFORMANCE`。讀自己 facts 的測試用 `FACT_KIT_FACTS` 指到 `facts/` 目錄。

fact_kit-0.3.0a1/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "fact-kit"
+version = "0.3.0-alpha.1"
+description = "Reads the fact packages built by fact-kit"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "fact-kit",
+    "facts",
+    "semver",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "orjson>=3.10",
+    "semver>=3.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/carlos-space/fact-kit"
+Issues = "https://github.com/carlos-space/fact-kit/issues"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fact_kit-0.3.0a1/pyproject.toml.orig

@@ -0,0 +1,31 @@
+[project]
+name = "fact-kit"
+version = "0.3.0-alpha.1"
+description = "Reads the fact packages built by fact-kit"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["fact-kit", "facts", "semver"]
+requires-python = ">=3.11"
+dependencies = [
+    "orjson>=3.10",
+    "semver>=3.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/carlos-space/fact-kit"
+Issues = "https://github.com/carlos-space/fact-kit/issues"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fact_kit-0.3.0a1/src/fact_kit/__init__.py

@@ -0,0 +1,17 @@
+"""Read the fact packages that fact-kit builds."""
+
+from ._errors import ERROR_CODES, ErrorCode, FactReadError
+from ._read import FactReader, read_facts
+from ._select import select_facts
+from ._version import compare_versions, release_line
+
+__all__ = [
+    "ERROR_CODES",
+    "ErrorCode",
+    "FactReadError",
+    "FactReader",
+    "compare_versions",
+    "read_facts",
+    "release_line",
+    "select_facts",
+]

fact_kit-0.3.0a1/src/fact_kit/_errors.py

@@ -0,0 +1,24 @@
+"""The error a reader raises."""
+
+from __future__ import annotations
+
+from typing import Final, Literal
+
+ErrorCode = Literal["not-an-index", "unsupported-index-format", "not-found", "invalid-version"]
+
+ERROR_CODES: Final[tuple[str, ...]] = (
+    "not-an-index",
+    "unsupported-index-format",
+    "not-found",
+    "invalid-version",
+)
+
+
+class FactReadError(Exception):
+    """A read failed. ``code`` is stable, the message is for people and can change."""
+
+    code: ErrorCode
+
+    def __init__(self, code: ErrorCode, message: str) -> None:
+        super().__init__(f"{message} ({code})")
+        self.code = code

fact_kit-0.3.0a1/src/fact_kit/_read.py

@@ -0,0 +1,113 @@
+"""``read_facts``: find an installed fact package, parse its index and select the facts of one reader."""
+
+from __future__ import annotations
+
+import os as _os
+from collections.abc import Iterable
+from typing import Any
+
+import orjson
+
+from ._errors import FactReadError
+from ._resolve import find_index_file
+from ._select import assert_index, select_facts
+
+
+def _owning_version(file: str, name: str) -> str:
+    """The ``package.json`` version of the package ``name`` that contains ``file``."""
+    directory = _os.path.dirname(file)
+    while True:
+        manifest = _os.path.join(directory, "package.json")
+        if _os.path.isfile(manifest):
+            try:
+                with open(manifest, "rb") as handle:
+                    data = orjson.loads(handle.read())
+            except (OSError, orjson.JSONDecodeError):
+                data = None
+            if isinstance(data, dict) and data.get("name") == name:
+                version = data.get("version")
+                return version if isinstance(version, str) else ""
+        parent = _os.path.dirname(directory)
+        if parent == directory:
+            return ""
+        directory = parent
+
+
+class FactReader:
+    """The facts one reader sees, from one installed ``index.json``."""
+
+    def __init__(
+        self,
+        *,
+        package: str,
+        version: str,
+        entry: str,
+        describes: dict[str, str],
+        facts: list[dict[str, Any]],
+    ) -> None:
+        self.package = package
+        """Name of the fact package, from the index."""
+        self.version = version
+        """Version of the installed fact package, from its ``package.json``."""
+        self.entry = entry
+        """Sub-path of the entry inside the package."""
+        self.describes = describes
+        """The component this entry describes and the version it covers."""
+        self.facts = facts
+        """The facts this reader sees, each flattened to the row that applies."""
+        self._by_id = {f["id"]: f for f in facts}
+
+    def has(self, id: str) -> bool:
+        """Whether a fact with this id exists."""
+        return id in self._by_id
+
+    def get(self, id: str) -> dict[str, Any]:
+        """The fact with this id. Raises ``KeyError`` when there is none, so a typo fails loudly."""
+        try:
+            return self._by_id[id]
+        except KeyError:
+            raise KeyError(f'read_facts: no fact "{id}" in {self.package}') from None
+
+    def value(self, id: str) -> Any:
+        """The ``content["value"]`` of the fact with this id. Raises ``ValueError`` without value content."""
+        content = self.get(id).get("content")
+        if not isinstance(content, dict) or "value" not in content:
+            raise ValueError(f'read_facts: fact "{id}" in {self.package} has no value content')
+        return content["value"]
+
+
+def read_facts(
+    spec: str,
+    *,
+    root: str | _os.PathLike[str] | None = None,
+    version: str | None = None,
+    include: Iterable[str] = (),
+    platform: str | None = None,
+    os: str | None = None,
+) -> FactReader:
+    """Read the built ``index.json`` of ``<package>`` or ``<package>/<path>`` as installed under ``root``.
+
+    The package is found the way Node's ``require.resolve`` finds it from ``root`` (default: the current
+    directory) and must export ``./index.json`` or ``./<path>/index.json``. The index may be format 1.0 or 1.1.
+    ``version``, ``include``, ``platform`` and ``os`` choose what the reader sees, see :func:`select_facts`.
+    Raises :class:`FactReadError`.
+    """
+    base = _os.getcwd() if root is None else _os.fspath(root)
+    base = _os.path.abspath(base)
+    file, package_name, entry = find_index_file(spec, base)
+    try:
+        with open(file, "rb") as handle:
+            index = orjson.loads(handle.read())
+    except (OSError, orjson.JSONDecodeError) as error:
+        raise FactReadError("not-an-index", f"read_facts: {file} is not a fact index ({error})") from error
+    assert_index(index, f"read_facts: {file}")
+    facts = select_facts(index, version=version, include=include, platform=platform, os=os)
+    describes = index.get("describes")
+    entry_name = index.get("entry")
+    return FactReader(
+        package=index["package"],
+        version=_owning_version(file, package_name),
+        entry=entry_name if isinstance(entry_name, str) else entry,
+        describes=describes if isinstance(describes, dict) else {},
+        facts=facts,
+    )

fact_kit-0.3.0a1/src/fact_kit/_resolve.py

@@ -0,0 +1,213 @@
+"""Find an installed ``index.json`` the way Node's ``require.resolve`` does.
+
+Covers self-reference, the ``node_modules`` walk, symlinked packages, and ``exports`` (strings, arrays,
+condition objects, nested conditions, ``*`` patterns, ``null``). ``NODE_PATH`` and the global folders are not
+searched.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+import orjson
+
+from ._errors import FactReadError
+
+# The conditions of `require`, in the sense of Node. Their order in `exports` is what counts, not this one.
+CONDITIONS = frozenset({"node-addons", "node", "require", "module-sync", "default"})
+
+
+class _InvalidTarget(Exception):
+    """An `exports` target that is not allowed. An array skips it, anything else gives up."""
+
+
+def split_spec(spec: str) -> tuple[str, str]:
+    """Split ``@scope/name/path`` or ``name/path`` into the package name and the sub-path (``""`` if none)."""
+    parts = spec.split("/")
+    name_length = 2 if spec.startswith("@") else 1
+    if len(parts) < name_length or any(not p for p in parts):
+        raise FactReadError(
+            "not-found", f'read_facts: "{spec}" is not of the form "<package>" or "<package>/<path>"'
+        )
+    name = "/".join(parts[:name_length])
+    if name.startswith(".") or "\\" in name or "%" in name or any(p in (".", "..") for p in parts):
+        raise FactReadError("not-found", f'read_facts: "{spec}" is not a valid package spec')
+    return name, "/".join(parts[name_length:])
+
+
+def _read_package_json(directory: str) -> dict[str, Any] | None:
+    """The parsed package.json of a directory, None if there is none. Unreadable JSON is `not-found`."""
+    path = os.path.join(directory, "package.json")
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, "rb") as handle:
+            data = orjson.loads(handle.read())
+    except (OSError, orjson.JSONDecodeError) as error:
+        raise FactReadError("not-found", f"cannot read {path} ({error})") from error
+    return data if isinstance(data, dict) else {}
+
+
+def _not_found(message: str) -> FactReadError:
+    return FactReadError("not-found", message)
+
+
+_INVALID_SEGMENT = re.compile(r"(?:\.|%2e){1,2}|node_modules|%6e%6f%64%65_modules", re.IGNORECASE)
+
+
+def _check_target(text: str) -> None:
+    if not text.startswith("./"):
+        raise _InvalidTarget(text)
+    for segment in re.split(r"[\\/]", text[2:]):
+        if segment and _INVALID_SEGMENT.fullmatch(segment):
+            raise _InvalidTarget(text)
+
+
+_UNDEFINED: Any = object()
+
+
+def _resolve_target(target: Any, match: str | None) -> Any:
+    """A relative path inside the package, None for `null`, or `_UNDEFINED` for no match.
+
+    Raises `_InvalidTarget`.
+    """
+    if isinstance(target, str):
+        _check_target(target)
+        if match is None:
+            return target
+        for segment in re.split(r"[\\/]", match):
+            if segment and _INVALID_SEGMENT.fullmatch(segment):
+                raise _InvalidTarget(target)
+        return target.replace("*", match)
+    if isinstance(target, list):
+        for item in target:
+            try:
+                found = _resolve_target(item, match)
+            except _InvalidTarget:
+                continue
+            if found is not _UNDEFINED and found is not None:
+                return found
+        return _UNDEFINED
+    if isinstance(target, dict):
+        if any(k.isdigit() for k in target):
+            raise _InvalidTarget("array index key")
+        for key, value in target.items():
+            if key in CONDITIONS:
+                found = _resolve_target(value, match)
+                if found is not _UNDEFINED:
+                    return found
+        return _UNDEFINED
+    if target is None:
+        return None
+    raise _InvalidTarget(str(target))
+
+
+def _pattern_compare(a: str, b: str) -> int:
+    base_a = a.index("*") + 1 if "*" in a else len(a)
+    base_b = b.index("*") + 1 if "*" in b else len(b)
+    if base_a > base_b:
+        return -1
+    if base_b > base_a:
+        return 1
+    if "*" not in a:
+        return 1
+    if "*" not in b:
+        return -1
+    if len(a) > len(b):
+        return -1
+    if len(b) > len(a):
+        return 1
+    return 0
+
+
+def _resolve_exports(exports: Any, subpath: str) -> Any:
+    """Node's PACKAGE_EXPORTS_RESOLVE for a require. Returns a relative path, or None when nothing matches."""
+    if isinstance(exports, dict):
+        dotted = [k for k in exports if k.startswith(".")]
+        if dotted and len(dotted) != len(exports):
+            raise _InvalidTarget("exports mixes subpaths and conditions")
+        if not dotted:
+            exports = {".": exports}
+    else:
+        exports = {".": exports}
+    if subpath in exports and "*" not in subpath and not subpath.endswith("/"):
+        return _resolve_target(exports[subpath], None)
+    best = ""
+    best_match = ""
+    for key in exports:
+        star = key.find("*")
+        if star == -1 or key.count("*") != 1 or subpath.endswith("/"):
+            continue
+        prefix, trailer = key[:star], key[star + 1 :]
+        if (
+            subpath.startswith(prefix)
+            and len(subpath) >= len(key)
+            and subpath.endswith(trailer)
+            and _pattern_compare(best, key) == 1
+        ):
+            best = key
+            best_match = subpath[len(prefix) : len(subpath) - len(trailer)]
+    if best:
+        return _resolve_target(exports[best], best_match)
+    return _UNDEFINED
+
+
+def _file_in(package_dir: str, relative: str) -> str:
+    path = os.path.normpath(os.path.join(package_dir, relative))
+    if not os.path.isfile(path):
+        raise _not_found(f"{path} does not exist")
+    return path
+
+
+def _resolve_in_package(package_dir: str, manifest: dict[str, Any] | None, entry: str, label: str) -> str:
+    subpath = f"./{entry}/index.json" if entry else "./index.json"
+    exports = manifest.get("exports") if manifest else None
+    if exports is None:
+        return _file_in(package_dir, subpath)
+    try:
+        relative = _resolve_exports(exports, subpath)
+    except _InvalidTarget as error:
+        raise _not_found(f'{label}: "{subpath}" has an invalid export ({error})') from error
+    if relative is _UNDEFINED or relative is None:
+        raise _not_found(f'{label}: the package does not export "{subpath}"')
+    return _file_in(package_dir, relative)
+
+
+def find_index_file(spec: str, root: str) -> tuple[str, str, str]:
+    """Locate ``<package>[/<path>]/index.json`` from ``root``. Returns (file, package name, entry)."""
+    name, entry = split_spec(spec)
+    label = f"read_facts({spec!r})"
+    # 1. Self-reference: the nearest package.json, when it is this package and has `exports`.
+    directory = root
+    while True:
+        manifest = _read_package_json(directory)
+        if manifest is not None:
+            if manifest.get("name") == name and manifest.get("exports") is not None:
+                return _resolve_in_package(directory, manifest, entry, label), name, entry
+            break
+        parent = os.path.dirname(directory)
+        if parent == directory:
+            break
+        directory = parent
+    # 2 and 3. The nearest node_modules/<name>, following symlinks.
+    directory = root
+    while True:
+        if os.path.basename(directory) != "node_modules":
+            candidate = os.path.join(directory, "node_modules", name)
+            if os.path.isdir(candidate):
+                package_dir = os.path.realpath(candidate)
+                manifest = _read_package_json(package_dir)
+                if manifest is not None and manifest.get("exports") is not None:
+                    return _resolve_in_package(package_dir, manifest, entry, label), name, entry
+                # 4. Without `exports` the path is a file path. When the file is not there, Node goes on to
+                # the next node_modules up.
+                subpath = f"{entry}/index.json" if entry else "index.json"
+                if os.path.isfile(os.path.join(package_dir, *subpath.split("/"))):
+                    return _resolve_in_package(package_dir, manifest, entry, label), name, entry
+        parent = os.path.dirname(directory)
+        if parent == directory:
+            break
+        directory = parent
+    raise _not_found(f"{label}: cannot find {name} from {root}. Install it there.")

fact_kit-0.3.0a1/src/fact_kit/_select.py

@@ -0,0 +1,247 @@
+"""Choose the facts one reader sees from a parsed ``index.json``."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import semver
+
+from ._errors import FactReadError
+from ._version import compare_lines, compare_semver, must_parse, parse_version
+
+NO_SINCE = "0.0.0"
+_MISSING: Any = object()
+
+# A bound is (rank, version): rank 0 is -inf, 1 is a version, 2 is +inf ("next").
+_Bound = tuple[int, semver.Version | None]
+_MIN: _Bound = (0, None)
+_MAX: _Bound = (2, None)
+
+
+@dataclass(frozen=True)
+class _Reader:
+    kind: str  # "head", "latest" or "version"
+    v: semver.Version | None = None
+
+
+def _truthy(x: Any) -> bool:
+    """JavaScript truthiness for a JSON value, so ``[]`` and ``{}`` count as set."""
+    return not (x is None or x is False or x == "" or (isinstance(x, (int, float)) and x == 0))
+
+
+def _compare_bounds(a: _Bound, b: _Bound) -> int:
+    if a[0] != b[0]:
+        return a[0] - b[0]
+    if a[0] == 1:
+        assert a[1] is not None and b[1] is not None
+        return compare_semver(a[1], b[1])
+    return 0
+
+
+def _rows_of(fact: Mapping[str, Any]) -> list[dict[str, Any]]:
+    """The rows of a fact. Without ``variants`` the whole fact is one row that starts at ``when.since``."""
+    variants = fact.get("variants")
+    if isinstance(variants, list):
+        rows = []
+        for v in variants:
+            if not isinstance(v, dict):
+                continue
+            row: dict[str, Any] = {}
+            for key in ("since", "content", "pending", "stability", "platforms", "os"):
+                if key in v:
+                    row[key] = v[key]
+            rows.append(row)
+        return rows
+    when = fact.get("when")
+    when = when if isinstance(when, dict) else {}
+    row = {}
+    if "since" in when:
+        row["since"] = when["since"]
+    if "content" in fact:
+        row["content"] = fact["content"]
+    for key in ("platforms", "os"):
+        if key in when:
+            row[key] = when[key]
+    return [row]
+
+
+def _bound_of(since: Any, reader: _Reader, fact_id: str) -> _Bound | None:
+    if since is _MISSING:
+        return _MIN
+    what = f"fact {fact_id}: since"
+    if since == "next" and isinstance(since, str):
+        return _MAX if reader.kind == "head" else None
+    if isinstance(since, str):
+        s = must_parse(since, what)
+        if reader.kind == "version":
+            assert reader.v is not None
+            return (1, s) if compare_semver(reader.v, s) >= 0 else None
+        return (1, s)
+    if not isinstance(since, list):
+        raise FactReadError("invalid-version", f"{what} must be a string or an array")
+    has_next = any(isinstance(s, str) and s == "next" for s in since)
+    versions = [must_parse(s, what) for s in since if not (isinstance(s, str) and s == "next")]
+    if not versions:
+        return _MAX if reader.kind == "head" else None
+    newest = versions[0]
+    for s in versions[1:]:
+        if compare_semver(s, newest) > 0:
+            newest = s
+    if reader.kind == "version":
+        assert reader.v is not None
+        same = next((s for s in versions if compare_lines(s, reader.v) == 0), None)
+        if same is not None:
+            return (1, same) if compare_semver(reader.v, same) >= 0 else None
+        # No version on the reader's line: the row applies once the reader's line is newer than all of them.
+        return (1, newest) if all(compare_lines(reader.v, s) > 0 for s in versions) else None
+    return _MAX if reader.kind == "head" and has_next else (1, newest)
+
+
+def _specificity(row: Mapping[str, Any]) -> int:
+    return (1 if _truthy(row.get("platforms")) else 0) + (1 if _truthy(row.get("os")) else 0)
+
+
+def _contains(listed: Any, value: Any) -> bool:
+    if isinstance(listed, (list, str)):
+        return value in listed
+    return False
+
+
+def _canonical(row: Mapping[str, Any]) -> str:
+    """The row as JSON with sorted keys and no whitespace, the text that breaks a tie."""
+    return json.dumps(row, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _utf16(text: str) -> bytes:
+    return text.encode("utf-16-be", "surrogatepass")
+
+
+def _choose_row(
+    rows: list[dict[str, Any]],
+    reader: _Reader,
+    include: Iterable[str],
+    platform: str | None,
+    os_name: str | None,
+    fact_id: str,
+) -> dict[str, Any] | None:
+    best: tuple[dict[str, Any], _Bound] | None = None
+    for row in rows:
+        if "pending" in row and not (reader.kind == "head" and _contains(list(include), row["pending"])):
+            continue
+        if _truthy(row.get("platforms")) and (platform is None or not _contains(row["platforms"], platform)):
+            continue
+        if _truthy(row.get("os")) and (os_name is None or not _contains(row["os"], os_name)):
+            continue
+        bound = _bound_of(row.get("since", _MISSING), reader, fact_id)
+        if bound is None:
+            continue
+        if best is None:
+            best = (row, bound)
+            continue
+        order = _compare_bounds(bound, best[1]) or _specificity(row) - _specificity(best[0])
+        # Equal rows are an author mistake that `check` reports. The canonical text keeps the result stable.
+        if order > 0 or (order == 0 and _utf16(_canonical(row)) < _utf16(_canonical(best[0]))):
+            best = (row, bound)
+    return best[0] if best else None
+
+
+def assert_index(index: Any, label: str = "the index") -> list[Any]:
+    """Check the top of an index and return its facts. Raises ``not-an-index`` or ``unsupported-index-format``."""
+    if not isinstance(index, dict):
+        raise FactReadError("not-an-index", f"{label} is not a fact index")
+    fmt = index["indexFormat"] if "indexFormat" in index else "1.0"
+    m = re.fullmatch(r"([0-9]+)\.[0-9]+", fmt, re.ASCII) if isinstance(fmt, str) else None
+    if m is None or int(m[1]) != 1:
+        raise FactReadError(
+            "unsupported-index-format",
+            f"{label} has index format {json.dumps(fmt)}, and this reader takes 1.x",
+        )
+    facts = index.get("facts")
+    if not isinstance(facts, list) or not isinstance(index.get("package"), str):
+        raise FactReadError("not-an-index", f"{label} is not a fact index")
+    return facts
+
+
+def _reader_of(version: Any) -> _Reader:
+    if version is None:
+        return _Reader("latest")
+    if version == "head" and isinstance(version, str):
+        return _Reader("head")
+    return _Reader("version", must_parse(version, "query version"))
+
+
+def _newest_released(facts: list[Any]) -> semver.Version | None:
+    newest: semver.Version | None = None
+    for fact in facts:
+        if not isinstance(fact, dict):
+            continue
+        for row in _rows_of(fact):
+            if "pending" in row or "since" not in row:
+                continue
+            since = row["since"]
+            for s in since if isinstance(since, list) else [since]:
+                v = None if s == "next" else parse_version(s)
+                if v is not None and (newest is None or compare_semver(v, newest) > 0):
+                    newest = v
+    return newest
+
+
+def _removed(fact: Mapping[str, Any], reader: _Reader, latest: semver.Version | None) -> bool:
+    when = fact.get("when")
+    at = when.get("removeIn") if isinstance(when, dict) else None
+    if not isinstance(at, str):
+        return False
+    if reader.kind == "head":
+        return True
+    if at == "next":
+        return False
+    gone = parse_version(at)
+    if gone is None:
+        return False
+    current = reader.v if reader.kind == "version" else latest
+    return current is not None and compare_semver(current, gone) >= 0
+
+
+def select_facts(
+    index: Mapping[str, Any],
+    *,
+    version: str | None = None,
+    include: Iterable[str] = (),
+    platform: str | None = None,
+    os: str | None = None,
+) -> list[dict[str, Any]]:
+    """The facts one reader sees, from a parsed ``index.json`` of format 1.0 or 1.1.
+
+    Each fact has rows (``variants``, or the whole fact as one row). A row applies when its ``since`` has been
+    reached, its ``pending`` label is included, and its ``platforms`` and ``os`` list the reader's. Of the rows
+    that apply the one with the largest bound wins, then the one with more conditions. A fact without an
+    applying row, or whose ``removeIn`` has been reached, is left out. The result keeps the order of the index.
+    Each returned dict is the fact with ``variants`` replaced by ``content``, ``since`` and ``stability``
+    of the chosen row.
+    """
+    facts = assert_index(index)
+    reader = _reader_of(version)
+    labels = list(include)
+    latest = _newest_released(facts) if reader.kind == "latest" else None
+    out: list[dict[str, Any]] = []
+    for fact in facts:
+        if not isinstance(fact, dict) or not isinstance(fact.get("id"), str):
+            continue
+        row = _choose_row(_rows_of(fact), reader, labels, platform, os, fact["id"])
+        if row is None or _removed(fact, reader, latest):
+            continue
+        selected = {k: v for k, v in fact.items() if k != "variants"}
+        if "content" in row:
+            selected["content"] = row["content"]
+        else:
+            selected.pop("content", None)
+        since = row.get("since")
+        selected["since"] = NO_SINCE if since is None else since
+        if "stability" in row:
+            selected["stability"] = row["stability"]
+        out.append(selected)
+    return out

fact_kit-0.3.0a1/src/fact_kit/_version.py

@@ -0,0 +1,54 @@
+"""Semver 2.0.0 parsing and precedence."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import semver
+
+from ._errors import FactReadError
+
+_SEMVER = re.compile(
+    r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)"
+    r"(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)"
+    r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?"
+    r"(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?",
+    re.ASCII,
+)
+
+
+def parse_version(text: Any) -> semver.Version | None:
+    """Parse a full ``X.Y.Z`` version, or return None. Build metadata is accepted and ignored."""
+    if not isinstance(text, str):
+        return None
+    m = _SEMVER.fullmatch(text)
+    if m is None:
+        return None
+    return semver.Version(int(m[1]), int(m[2]), int(m[3]), m[4], m[5])
+
+
+def must_parse(text: Any, what: str) -> semver.Version:
+    v = parse_version(text)
+    if v is None:
+        raise FactReadError("invalid-version", f'{what} "{text}" is not a semver 2.0.0 version')
+    return v
+
+
+def compare_semver(a: semver.Version, b: semver.Version) -> int:
+    return a.compare(b)
+
+
+def compare_lines(a: semver.Version, b: semver.Version) -> int:
+    return (a.major > b.major) - (a.major < b.major) or (a.minor > b.minor) - (a.minor < b.minor)
+
+
+def compare_versions(a: str, b: str) -> int:
+    """Compare two versions by semver precedence: -1, 0 or 1. Raises ``invalid-version``."""
+    return compare_semver(must_parse(a, "version"), must_parse(b, "version"))
+
+
+def release_line(version: str) -> str:
+    """The release line ``X.Y`` of a version. ``0.49.0-alpha.1`` is on line ``0.49``."""
+    v = must_parse(version, "version")
+    return f"{v.major}.{v.minor}"