index.toml-contracts 0.1.0__tar.gz

index_toml_contracts-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.3
+Name: index.toml-contracts
+Version: 0.1.0
+Summary: Schema and validation for ecosystem-neutral package indexes
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: jsonschema>=4.22,<5
+Requires-Dist: tomli>=2,<3 ; python_full_version < '3.11'
+Requires-Python: >=3.10, <3.16
+Project-URL: Repository, https://github.com/groupsum/index.toml
+Description-Content-Type: text/markdown
+
+# index.toml Contracts
+
+The distribution includes `index-v1.schema.json`, a JSON Schema for the data decoded from a UTF-8 TOML index. The Python API provides `schema()`, `validate(mapping)`, `loads(text)`, and `load(path)`. Invalid input raises `IndexValidationError`.
+
+Validation covers record structure, portable paths, layer and package references, dependency policy, and cycles. Any language can use the bundled schema and implement the semantic rules described in the [repository contract](https://github.com/groupsum/index.toml/blob/master/README.md).

index_toml_contracts-0.1.0/README.md

@@ -0,0 +1,5 @@
+# index.toml Contracts
+
+The distribution includes `index-v1.schema.json`, a JSON Schema for the data decoded from a UTF-8 TOML index. The Python API provides `schema()`, `validate(mapping)`, `loads(text)`, and `load(path)`. Invalid input raises `IndexValidationError`.
+
+Validation covers record structure, portable paths, layer and package references, dependency policy, and cycles. Any language can use the bundled schema and implement the semantic rules described in the [repository contract](https://github.com/groupsum/index.toml/blob/master/README.md).

index_toml_contracts-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "index.toml-contracts"
+version = "0.1.0"
+description = "Schema and validation for ecosystem-neutral package indexes"
+readme = "README.md"
+requires-python = ">=3.10,<3.16"
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "jsonschema>=4.22,<5",
+    "tomli>=2,<3; python_version < '3.11'",
+]
+
+[project.urls]
+Repository = "https://github.com/groupsum/index.toml"
+
+[[tool.uv.cache-keys]]
+file = "pyproject.toml"
+
+[[tool.uv.cache-keys]]
+file = "README.md"
+
+[[tool.uv.cache-keys]]
+file = "src/**/*"
+
+[build-system]
+requires = ["uv_build>=0.9,<1"]
+build-backend = "uv_build"

index_toml_contracts-0.1.0/pyproject.toml.orig

@@ -0,0 +1,28 @@
+[project]
+name = "index.toml-contracts"
+version = "0.1.0"
+description = "Schema and validation for ecosystem-neutral package indexes"
+readme = "README.md"
+requires-python = ">=3.10,<3.16"
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "jsonschema>=4.22,<5",
+    "tomli>=2,<3; python_version < '3.11'",
+]
+
+[project.urls]
+Repository = "https://github.com/groupsum/index.toml"
+
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { file = "README.md" }, { file = "src/**/*" }]
+
+[build-system]
+requires = ["uv_build>=0.9,<1"]
+build-backend = "uv_build"

index_toml_contracts-0.1.0/src/index_toml_contracts/__init__.py

@@ -0,0 +1,141 @@
+"""Portable package index schema and validation."""
+
+import json
+import sys
+from graphlib import CycleError, TopologicalSorter
+from importlib.resources import files
+from pathlib import Path
+
+from jsonschema import Draft202012Validator, validators
+
+from .workspace import (
+    WorkspaceAdapter as WorkspaceAdapter,
+    WorkspaceDependency as WorkspaceDependency,
+    WorkspaceDiagnostic as WorkspaceDiagnostic,
+    WorkspaceMember as WorkspaceMember,
+    WorkspaceSnapshot as WorkspaceSnapshot,
+)
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+class IndexValidationError(ValueError):
+    """The document violates the index contract."""
+
+
+def read_workspace_toml(path: Path) -> dict:
+    """Decode a workspace manifest without applying the package index schema."""
+    return tomllib.loads(path.read_bytes().decode("utf-8"))
+
+
+def schema() -> dict:
+    """Return a fresh copy of the bundled JSON Schema."""
+    return json.loads(files(__package__).joinpath("index-v1.schema.json").read_text(
+        encoding="utf-8"
+    ))
+
+
+# JSON Schema normally treats integral floats as integers. TOML distinguishes them.
+_TomlValidator = validators.extend(
+    Draft202012Validator,
+    type_checker=Draft202012Validator.TYPE_CHECKER.redefine(
+        "integer", lambda checker, value: type(value) is int
+    ),
+)
+_validator = _TomlValidator(schema())
+SCHEMA_VERSION = _validator.schema["properties"]["schema_version"]["const"]
+
+
+def _by_id(records: list[dict], kind: str) -> dict[str, dict]:
+    by_id = {}
+    for record in records:
+        identifier = record["id"]
+        if identifier in by_id:
+            raise IndexValidationError(f"Duplicate {kind} ID {identifier!r}")
+        by_id[identifier] = record
+    return by_id
+
+
+def _validate_path(path: str) -> None:
+    if path == ".":
+        return
+    invalid = '\\:<>|"?' + chr(42)
+    if any(char in invalid or ord(char) < 32 for char in path) or any(
+        part in ("", ".", "..") or part.endswith((".", " ")) for part in path.split("/")
+    ):
+        raise IndexValidationError(f"Invalid repository-relative path {path!r}")
+
+
+def _validate_packages(layers: dict[str, dict], packages: dict[str, dict]) -> None:
+    for identifier, package in packages.items():
+        _validate_path(package["path"])
+        if package["layer"] not in layers:
+            raise IndexValidationError(f"Package {identifier!r} references an unknown layer")
+        dependencies = set(package.get("dependencies", []))
+        exceptions = set(package.get("dependency_exceptions", []))
+        if exceptions - dependencies:
+            raise IndexValidationError(f"Package {identifier!r} excepts undeclared dependencies")
+        for dependency in dependencies:
+            if dependency == identifier or dependency not in packages:
+                raise IndexValidationError(f"Invalid dependency {identifier!r} -> {dependency!r}")
+            if dependency in exceptions:
+                continue
+            target = packages[dependency]
+            source_layer = layers[package["layer"]]
+            target_layer = layers[target["layer"]]
+            allowed = source_layer.get("allowed_dependency_layers")
+            if package["layer"] == target["layer"]:
+                permitted = target["order"] < package["order"]
+            elif allowed is None:
+                permitted = target_layer["order"] < source_layer["order"]
+            else:
+                permitted = target["layer"] in allowed
+            if not permitted:
+                raise IndexValidationError(f"Dependency policy rejects {identifier!r} -> {dependency!r}")
+
+    graph = TopologicalSorter({
+        identifier: package.get("dependencies", [])
+        for identifier, package in packages.items()
+    })
+    try:
+        graph.prepare()
+    except CycleError as error:
+        raise IndexValidationError(f"Package dependency cycle: {' -> '.join(error.args[1])}") from error
+
+
+def validate(index: dict) -> None:
+    """Validate the decoded TOML structure, references, paths and dependency graph."""
+    error = next(_validator.iter_errors(index), None)
+    if error is not None:
+        raise IndexValidationError(f"{error.json_path}: {error.message}")
+
+    layers = _by_id(index["layers"], "layer")
+    packages = _by_id(index["packages"], "package")
+    if len({layer["order"] for layer in layers.values()}) != len(layers):
+        raise IndexValidationError("Layer orders must be unique")
+    for identifier, layer in layers.items():
+        for target in layer.get("allowed_dependency_layers", []):
+            if target == identifier or target not in layers:
+                raise IndexValidationError(f"Invalid allowed layer {identifier!r} -> {target!r}")
+    _validate_packages(layers, packages)
+
+
+def loads(source: str) -> dict:
+    """Parse and validate an index from TOML text."""
+    try:
+        index = tomllib.loads(source)
+    except tomllib.TOMLDecodeError as error:
+        raise IndexValidationError(f"Invalid TOML: {error}") from error
+    validate(index)
+    return index
+
+
+def load(path: str | Path) -> dict:
+    """Read, parse and validate an index from disk."""
+    try:
+        return loads(Path(path).read_text(encoding="utf-8"))
+    except UnicodeDecodeError as error:
+        raise IndexValidationError("Index must be UTF-8") from error

index_toml_contracts-0.1.0/src/index_toml_contracts/index-v1.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Package index 1.0.0",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "layers", "packages"],
+  "properties": {
+    "schema_version": {"type": "string", "const": "1.0.0"},
+    "layers": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/layer"}
+    },
+    "packages": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/package"}
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$"
+    },
+    "order": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9223372036854775807
+    },
+    "ids": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {"$ref": "#/$defs/id"}
+    },
+    "layer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "order"],
+      "properties": {
+        "id": {"$ref": "#/$defs/id"},
+        "order": {"$ref": "#/$defs/order"},
+        "description": {"type": "string"},
+        "allowed_dependency_layers": {"$ref": "#/$defs/ids"}
+      }
+    },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "layer", "order", "path"],
+      "properties": {
+        "id": {"$ref": "#/$defs/id"},
+        "layer": {"$ref": "#/$defs/id"},
+        "order": {"$ref": "#/$defs/order"},
+        "path": {"type": "string", "minLength": 1},
+        "name": {"type": "string", "minLength": 1},
+        "ecosystem": {"type": "string", "minLength": 1},
+        "description": {"type": "string"},
+        "dependencies": {"$ref": "#/$defs/ids"},
+        "dependency_exceptions": {"$ref": "#/$defs/ids"}
+      }
+    }
+  }
+}

index_toml_contracts-0.1.0/src/index_toml_contracts/workspace.py

@@ -0,0 +1,46 @@
+"""Shared types for read-only workspace discovery."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class WorkspaceMember:
+    name: str
+    identity: str
+    path: str
+    manifest: str
+
+
+@dataclass(frozen=True)
+class WorkspaceDependency:
+    source: str
+    target: str
+    category: str
+    manifest: str
+    declaration: str
+    condition: str | None = None
+
+
+@dataclass(frozen=True)
+class WorkspaceDiagnostic:
+    code: str
+    manifest: str
+    message: str
+
+
+@dataclass(frozen=True)
+class WorkspaceSnapshot:
+    members: tuple[WorkspaceMember, ...] = ()
+    dependencies: tuple[WorkspaceDependency, ...] = ()
+    diagnostics: tuple[WorkspaceDiagnostic, ...] = ()
+
+
+class WorkspaceAdapter(Protocol):
+    name: str
+    ecosystem: str
+
+    def normalize_name(self, name: str) -> str: ...
+
+    def discover(self, root: Path) -> WorkspaceSnapshot: ...