SciAPI 0.0.0__tar.gz → 0.0.1__tar.gz

sciapi-0.0.1/.gitignore

@@ -0,0 +1,4 @@
+# The ignore rules of the package folder. hatchling puts the nearest
+# .gitignore into the sdist, so this one stands in for the repository's.
+__pycache__/
+*.py[cod]

sciapi-0.0.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: sciapi
+Version: 0.0.1
+Summary: Extract, check, generate, and document Python and native library interfaces.
+Requires-Python: >=3.12
+Requires-Dist: griffe==2.4.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonschema>=4.26
+Requires-Dist: markdown-it-py>=4
+Requires-Dist: pydantic>=2.14
+Requires-Dist: typing-extensions>=4.16
+Provides-Extra: sphinx
+Requires-Dist: myst-parser>=5; extra == 'sphinx'
+Requires-Dist: sphinx>=8.2; extra == 'sphinx'

sciapi-0.0.1/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sciapi"
+dynamic = ["version"]
+description = "Extract, check, generate, and document Python and native library interfaces."
+requires-python = ">=3.12"
+dependencies = [
+  # Exact, since the shipped schema python-public.schema.json is derived from
+  # the serialization of this version.
+  "griffe==2.4.1",
+  "jinja2>=3.1",
+  "jsonschema>=4.26",
+  "markdown-it-py>=4",
+  "pydantic>=2.14",
+  "typing-extensions>=4.16",
+]
+
+[project.optional-dependencies]
+# The Sphinx extension `sciapi.sphinxext`, which renders references in MyST.
+sphinx = ["myst-parser>=5", "sphinx>=8.2"]
+
+[project.scripts]
+sciapi = "sciapi.cli:main"
+
+[tool.hatch.version]
+path = "sciapi/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sciapi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/sciapi"]

sciapi-0.0.1/sciapi/__init__.py

@@ -0,0 +1,86 @@
+"""Extract, verify, generate and document independently observed interfaces."""
+
+from sciapi._diagnostics import Finding
+from sciapi._version import __version__ as __version__
+from sciapi.comparison._check import check
+from sciapi.comparison._conformance import conformance
+from sciapi.comparison.cross_language.compare import compare_contracts
+from sciapi.comparison.cross_language.config import ContractConfig
+from sciapi.comparison.cross_language.evidence import CoverageEvidence
+from sciapi.comparison.cross_language.evidence_validation import (
+    validate_behavioral_coverage,
+)
+from sciapi.comparison.cross_language.report import ContractReport
+from sciapi.comparison.cross_language.requirements import (
+    RequirementSet,
+    behavioral_requirements,
+)
+from sciapi.comparison.cross_language.results import (
+    ConformanceResult,
+    CoverageResult,
+)
+from sciapi.comparison.history import (
+    Change,
+    ChangePolicy,
+    ChangeReport,
+    VersionDecision,
+    VersionPolicy,
+    compare_snapshots,
+    evaluate_version,
+)
+from sciapi.comparison.receipts import read_check
+from sciapi.comparison.results import CheckResult
+from sciapi.config._project import Project
+from sciapi.extraction._extract import extract
+from sciapi.python_generation._generate import generate
+from sciapi.python_generation.results import (
+    GeneratedFile,
+    GenerationDecision,
+    GenerationPlanSummary,
+    GenerationResult,
+)
+from sciapi.references._reference import reference
+from sciapi.references.results import ReferenceResult
+from sciapi.snapshots._readers import read_bundle
+from sciapi.snapshots.bundles import Artifact, Bundle
+from sciapi.workflows.results import WorkflowResult
+from sciapi.workflows.session import PipelineSession, run
+
+__all__ = [
+    "Artifact",
+    "Bundle",
+    "Change",
+    "ChangePolicy",
+    "ChangeReport",
+    "CheckResult",
+    "ConformanceResult",
+    "ContractConfig",
+    "ContractReport",
+    "CoverageEvidence",
+    "CoverageResult",
+    "Finding",
+    "GeneratedFile",
+    "GenerationDecision",
+    "GenerationPlanSummary",
+    "GenerationResult",
+    "PipelineSession",
+    "Project",
+    "ReferenceResult",
+    "RequirementSet",
+    "VersionDecision",
+    "VersionPolicy",
+    "WorkflowResult",
+    "behavioral_requirements",
+    "check",
+    "compare_contracts",
+    "compare_snapshots",
+    "conformance",
+    "evaluate_version",
+    "extract",
+    "generate",
+    "read_bundle",
+    "read_check",
+    "reference",
+    "run",
+    "validate_behavioral_coverage",
+]

sciapi-0.0.1/sciapi/__main__.py

@@ -0,0 +1,5 @@
+"""Execute the public command-line interface."""
+
+from sciapi.cli import main
+
+raise SystemExit(main())

sciapi-0.0.1/sciapi/_compiler_locations.py

@@ -0,0 +1,51 @@
+"""Normalize compiler-location identities without consulting live sources."""
+
+from __future__ import annotations
+
+import ntpath
+import posixpath
+from pathlib import PurePath, PurePosixPath, PureWindowsPath
+from urllib.parse import unquote, urlparse
+
+__all__: list[str] = []
+
+
+def source_path(value: str) -> str:
+    """Decode a file URI, preserving remote hosts and Windows drive roots."""
+    parsed = urlparse(value)
+    if parsed.scheme != "file":
+        return value
+    path = unquote(parsed.path)
+    if parsed.netloc and parsed.netloc.casefold() != "localhost":
+        return "//" + parsed.netloc + path
+    if path.startswith("/") and PureWindowsPath(path[1:]).drive:
+        return path[1:]
+    return path
+
+
+def logical_path(value: str) -> PurePath:
+    """Select the compiler path's own flavor and normalize it lexically."""
+    path = source_path(value)
+    if "\\" in path or PureWindowsPath(path).drive:
+        return PureWindowsPath(ntpath.normpath(path))
+    return PurePosixPath(posixpath.normpath(path))
+
+
+def location_identity(value: str, root: PurePath | None = None) -> str:
+    """Normalize an identity with its compiler path's case rules."""
+    path = logical_path(value)
+    if root is not None and not path.is_absolute():
+        path = logical_path((root / path.as_posix()).as_posix())
+    identity = path.as_posix()
+    if isinstance(path, PureWindowsPath):
+        return identity.casefold()
+    return identity
+
+
+def resolve_compiler_root(value: str | PurePath, base: PurePath) -> str:
+    """Preserve foreign absolute roots and resolve relative roots lexically."""
+    path = logical_path(str(value))
+    if path.is_absolute():
+        return str(value)
+    parent = logical_path(str(base))
+    return logical_path((parent / path.as_posix()).as_posix()).as_posix()

sciapi-0.0.1/sciapi/_declarations/__init__.py

@@ -0,0 +1 @@
+"""Private helpers for captured interface declarations."""

sciapi-0.0.1/sciapi/_declarations/_reference_rows.py

@@ -0,0 +1,95 @@
+"""Stable rows and path targets shared by saved declaration consumers."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any
+
+Row = dict[str, Any]
+
+_CONTAINERS = {
+    "module",
+    "class",
+    "exception",
+    "struct",
+    "enum",
+    "trait",
+    "union",
+    "c.struct",
+    "c.enum",
+    "c.union",
+}
+
+
+def _kind(row: Row) -> str:
+    return str(row.get("kind", "")).replace(" ", "_")
+
+
+_READABLE_PATH = re.compile(r"[A-Za-z_]\w*(?:(?:\.|::)[A-Za-z_]\w*)+", re.ASCII)
+
+
+def public_anchor(path: str) -> str:
+    """Return the stable target shared by raw and expanded public bindings.
+
+    A path of two or more identifiers joined by dots or ``::`` is its own
+    anchor, as in Sphinx's Python domain. Its separator keeps it distinct from
+    heading and other generated identifiers, which never contain one. Any other
+    path, including a single name, becomes a lowercase slug with a digest
+    suffix; its hyphens keep it distinct from every readable anchor.
+    """
+    if _READABLE_PATH.fullmatch(path):
+        return path
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", path).strip("-").lower()[:80]
+    return f"api-{slug}-{hashlib.sha256(path.encode()).hexdigest()[:10]}"
+
+
+def _parent(path: str, separator: str, paths: dict[str, Row]) -> str:
+    while separator in path:
+        path = path.rsplit(separator, 1)[0]
+        if path in paths and _kind(paths[path]) in _CONTAINERS:
+            return path
+    return ""
+
+
+def _metadata(value: dict[str, Any]) -> dict[str, Any]:
+    meta = value.get("x-api-tools", {})
+    return meta if isinstance(meta, dict) else {}
+
+
+def _base_row(path: str, kind: str, *, level: int = 2) -> dict[str, Any]:
+    return {
+        "path": path,
+        "kind": kind,
+        "anchor": public_anchor(path),
+        "level": min(level, 6),
+        "alias": False,
+        "canonical_path": path,
+        "canonical_anchor": public_anchor(path),
+        "signature": "",
+        "annotation": "",
+        "value": "",
+        "required": None,
+        "readonly": False,
+        "sections": [],
+        "doc": "",
+        "abi": "",
+        "object_kind": kind,
+        "references": [],
+        "module": "",
+        "class_name": "",
+        "owner": "",
+        "bases": [],
+        "labels": [],
+        "declaration_kind": "",
+        "named_tuple_fields": [],
+        "type_parameters": [],
+        "parameter_specs": [],
+        "model_fields": [],
+        "limits": [],
+        "full_value": "",
+        "declaration_name": "",
+        "parameters": [],
+        "returns": "",
+        "constructor_in_class": False,
+    }

sciapi-0.0.1/sciapi/_declarations/native/__init__.py

@@ -0,0 +1,3 @@
+"""Pure views of captured native declaration records."""
+
+__all__: list[str] = []

sciapi-0.0.1/sciapi/_declarations/native/_formats.py

@@ -0,0 +1,23 @@
+"""Identify the declaration language of a captured document format."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def declaration_language(format_name: str, document: dict[str, Any]) -> str:
+    if (
+        "griffe" in format_name
+        or format_name == "python"
+        or document.get("kind") == "module"
+    ):
+        return "python"
+    if "rustdoc" in format_name:
+        return "rust"
+    if any(
+        value in format_name
+        for value in ("clang", "symbolgraph", "symbol-graph")
+    ):
+        return "c"
+    msg = f"Unsupported reference format: {format_name}"
+    raise ValueError(msg)

sciapi-0.0.1/sciapi/_declarations/native/_public_bindings.py

@@ -0,0 +1,123 @@
+"""Expand only compiler-proven native forwarding container bindings."""
+
+from __future__ import annotations
+
+from collections import deque
+from copy import deepcopy
+from dataclasses import dataclass, field
+
+from sciapi._declarations._reference_rows import (
+    _CONTAINERS,
+    Row,
+    _kind,
+    _parent,
+    public_anchor,
+)
+
+
+@dataclass
+class _NativeBindings:
+    """Compiler rows plus the proven forwarding spellings expanded from them."""
+
+    originals: dict[str, Row]
+    expanded: dict[str, Row] = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.expanded = dict(self.originals)
+
+    def definition(self, path: str) -> str:
+        seen: set[str] = set()
+        while path in self.originals and self.originals[path].get("alias"):
+            if path in seen:
+                msg = f"Cyclic reference alias: {path}"
+                raise ValueError(msg)
+            seen.add(path)
+            path = str(self.originals[path].get("canonical_path", ""))
+        return path
+
+    def identity(self, path: str) -> str:
+        return (
+            self.definition(path)
+            if path in self.originals
+            else str(self.expanded[path]["canonical_path"])
+        )
+
+    def recursive(self, path: str, target: str) -> bool:
+        while "::" in path:
+            path = path.rsplit("::", 1)[0]
+            if path in self.expanded and self.identity(path) == target:
+                return True
+        return False
+
+    def forward(self, path: str, child: str, item: Row) -> str | None:
+        target = self.identity(path)
+        spelling = path + child[len(target) :]
+        child_identity = self.definition(child)
+        if spelling in self.expanded:
+            if self.identity(spelling) != child_identity:
+                msg = f"Conflicting compiler-proven public binding: {spelling}"
+                raise ValueError(msg)
+            return None
+        copy = deepcopy(item)
+        copy.update(
+            path=spelling,
+            anchor=public_anchor(spelling),
+            alias=True,
+            canonical_path=child_identity,
+            expanded=True,
+        )
+        self.expanded[spelling] = copy
+        return spelling
+
+    def expand(self) -> None:
+        # Newly proven spellings can themselves forward container aliases.
+        pending = deque(sorted(self.originals))
+        while pending:
+            path = pending.popleft()
+            row = self.expanded[path]
+            target = self.identity(path)
+            source = self.originals.get(target)
+            if (
+                not row.get("alias")
+                or source is None
+                or _kind(source) not in _CONTAINERS
+                or self.recursive(path, target)
+            ):
+                continue
+            for child, item in self.originals.items():
+                if child.startswith(target + "::"):
+                    spelling = self.forward(path, child, item)
+                    if spelling is not None:
+                        pending.append(spelling)
+
+    def rows(self) -> list[Row]:
+        result = []
+        for path, row in sorted(self.expanded.items()):
+            identity = self.identity(path)
+            item = deepcopy(self.originals.get(identity, row))
+            item.update(
+                path=path,
+                anchor=str(row["anchor"]),
+                definition_path=identity,
+                inventory_alias=bool(row.get("alias", False)),
+                inventory_kind=str(row.get("kind", "")),
+                expanded=bool(row.get("expanded", False)),
+                documentation_parent=_parent(path, "::", self.expanded),
+                documentation_inherited=False,
+                external=identity not in self.originals,
+            )
+            result.append(item)
+        effective = {str(row["path"]): row for row in result}
+        for row in result:
+            row["documentation_parent"] = _parent(
+                str(row["path"]), "::", effective
+            )
+        return result
+
+
+def expand_native_bindings(rows: list[Row], language: str) -> list[Row]:
+    """Retain compiler identities and expand only proven container aliases."""
+    bindings = _NativeBindings({str(row["path"]): row for row in rows})
+    if language == "rust":
+        bindings.expand()
+    return bindings.rows()

sciapi-0.0.1/sciapi/_declarations/native/_public_signatures.py

@@ -0,0 +1,43 @@
+"""Project compiler-prepared declaration names to public native spellings."""
+
+from __future__ import annotations
+
+import re
+
+
+def public_signature(
+    signature: str, declaration_name: str, public: str, kind: str
+) -> str:
+    """Change only the compiler-prepared declaration's known name token."""
+    old = declaration_name
+    new = public.rsplit("::", 1)[-1]
+    if old == new:
+        return signature
+    token = {
+        "function": "fn",
+        "method": "fn",
+        "module": "mod",
+        "struct": "struct",
+        "enum": "enum",
+        "trait": "trait",
+        "union": "union",
+        "type_alias": "type",
+        "trait_alias": "trait",
+        "assoc_type": "type",
+        "constant": "const",
+        "assoc_const": "const",
+        "static": "static",
+        "macro": r"macro(?:_rules!)?",
+    }.get(kind)
+    if token is None:
+        return signature
+    return re.sub(
+        r"(\b"
+        + token
+        + r"\s+)(?:r#)?"
+        + re.escape(old.removeprefix("r#"))
+        + r"(?=\W|$)",
+        lambda match: match[1] + new,
+        signature,
+        count=1,
+    )