nativegate 0.1.0__py3-none-any.whl

nativegate/suggest.py

@@ -0,0 +1,208 @@
+"""Rank the native sources in a tree by how cleanly they would bind.
+
+The information needed to pick a starting file already exists — `inspect`
+prints it — but only one file at a time, for someone who already knows which
+files are candidates. Someone meeting a C++ codebase for the first time does
+not, and the cost of guessing wrong is a service that half-binds and fails
+later. This module runs the parse across a whole tree and sorts the results,
+so the answer to "which file do I point at" is the first row of a table.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import ExposeConfig
+from .discovery import find_implementation_files, find_native_sources
+from .ir import ModuleIR
+from .parsers import cpp as cpp_parser
+from .parsers.cpp_ast import ClangOptions
+from .parsers import fortran as fortran_parser
+
+# Verdicts, in ranking order. READY files bind everything they declare;
+# WORKABLE ones bind more than they skip; POOR ones bind nothing useful.
+READY = "ready"
+WORKABLE = "workable"
+POOR = "poor"
+
+_QUOTED_INCLUDE = re.compile(r'^\s*#\s*include\s*"([^"]+)"', re.MULTILINE)
+
+# Headers-only extensions: these are what you point nativegate at. A bare .cpp
+# is an implementation file, not an interface, so it is not offered as a
+# candidate unless nothing else exists.
+_HEADER_SUFFIXES = {".hpp", ".hh", ".h"}
+
+
+@dataclass
+class Candidate:
+    """One native source, and how well it would bind."""
+
+    path: Path
+    language: str
+    verdict: str
+    bound: int = 0
+    skipped: int = 0
+    classes: int = 0
+    structs: int = 0
+    functions: int = 0
+    methods: int = 0
+    impl_files: list[Path] = field(default_factory=list)
+    local_includes: list[str] = field(default_factory=list)
+    error: str | None = None
+
+    @property
+    def sort_key(self) -> tuple:
+        # Dependencies dominate, ahead of skip count: one skipped array method
+        # out of twenty costs you that method, while one #include of another
+        # subsystem's header costs you that whole subsystem's build. Only
+        # outright unusable files (POOR) sort below a dependency-heavy one.
+        return (
+            1 if self.verdict == POOR else 0,
+            len(self.local_includes),
+            self.skipped,
+            -self.bound,
+            str(self.path),
+        )
+
+    def binds_summary(self) -> str:
+        parts = []
+        if self.functions:
+            parts.append(f"{self.functions} fn")
+        if self.classes:
+            parts.append(f"{self.classes} class")
+        if self.methods:
+            parts.append(f"{self.methods} method")
+        if self.structs:
+            parts.append(f"{self.structs} struct")
+        return ", ".join(parts) or "nothing"
+
+    def notes(self) -> str:
+        if self.error:
+            return self.error
+        notes = []
+        if self.impl_files:
+            notes.append(", ".join(f.name for f in self.impl_files))
+        elif self.language == "cpp" and (self.methods or self.functions):
+            notes.append("no .cpp found")
+        if self.local_includes:
+            shown = sorted(self.local_includes)
+            extra = ""
+            if len(shown) > 2:
+                shown, extra = shown[:2], f" +{len(self.local_includes) - 2}"
+            notes.append("needs " + ", ".join(shown) + extra)
+        return "; ".join(notes)
+
+
+def _local_includes(source: Path, impl_files: list[Path]) -> list[str]:
+    """Quoted #includes that resolve to a real neighbouring header.
+
+    Scans the implementation files too: a header can look self-contained
+    while its .cpp pulls in a bridge to another subsystem, and that
+    dependency is exactly what makes a file a poor first choice.
+    """
+    found: set[str] = set()
+    for path in [source, *impl_files]:
+        try:
+            text = path.read_text(errors="replace")
+        except OSError:
+            continue
+        for name in _QUOTED_INCLUDE.findall(text):
+            included = Path(name).name
+            if Path(included).stem == source.stem:
+                continue  # the .cpp including its own header
+            # Only count it if it actually exists nearby — a missing include
+            # is a build problem, not a dependency worth ranking on.
+            if (path.parent / name).exists() or (source.parent / included).exists():
+                found.add(included)
+    return sorted(found)
+
+
+def _classify(module: ModuleIR, local_includes: list[str]) -> tuple[str, dict]:
+    methods = sum(len(cls.methods) for cls in module.classes)
+    counts = {
+        "classes": len(module.classes),
+        "structs": len(module.structs),
+        "functions": len(module.functions),
+        "methods": methods,
+    }
+    bound = methods + len(module.functions) + len(module.structs)
+    skipped = len(module.skipped)
+
+    if bound == 0 or skipped >= bound:
+        verdict = POOR
+    elif skipped == 0 and not local_includes:
+        # Turnkey: everything it declares binds, and it drags nothing else in.
+        verdict = READY
+    else:
+        verdict = WORKABLE
+    return verdict, {"bound": bound, "skipped": skipped, **counts}
+
+
+def _analyse_cpp(source: Path, backend: str, options: ClangOptions) -> Candidate:
+    impl_files = find_implementation_files(source)
+    try:
+        module = cpp_parser.parse_header(
+            source, ExposeConfig(), backend=backend, options=options
+        )
+    except Exception as exc:  # a header that will not parse is a real answer
+        return Candidate(
+            path=source,
+            language="cpp",
+            verdict=POOR,
+            impl_files=impl_files,
+            error=f"parse failed: {type(exc).__name__}",
+        )
+
+    local_includes = _local_includes(source, impl_files)
+    verdict, counts = _classify(module, local_includes)
+    return Candidate(
+        path=source,
+        language="cpp",
+        verdict=verdict,
+        impl_files=impl_files,
+        local_includes=local_includes,
+        **counts,
+    )
+
+
+def _analyse_fortran(source: Path) -> Candidate:
+    try:
+        routines = fortran_parser.list_routine_names(source)
+    except Exception as exc:
+        return Candidate(
+            path=source,
+            language="fortran",
+            verdict=POOR,
+            error=f"parse failed: {type(exc).__name__}",
+        )
+    return Candidate(
+        path=source,
+        language="fortran",
+        verdict=READY if routines else POOR,
+        bound=len(routines),
+        functions=len(routines),
+    )
+
+
+def analyse_tree(
+    root: Path,
+    backend: str = "auto",
+    options: ClangOptions | None = None,
+) -> list[Candidate]:
+    """Parse every native source under `root`, best starting point first."""
+    options = options or ClangOptions()
+    candidates: list[Candidate] = []
+
+    cpp_sources = find_native_sources(root, "cpp")
+    headers = [p for p in cpp_sources if p.suffix.lower() in _HEADER_SUFFIXES]
+    # Prefer headers; fall back to .cpp only for projects that have no headers
+    # at all, where the .cpp really is the interface.
+    for source in headers or cpp_sources:
+        candidates.append(_analyse_cpp(source, backend, options))
+
+    for source in find_native_sources(root, "fortran"):
+        candidates.append(_analyse_fortran(source))
+
+    return sorted(candidates, key=lambda c: c.sort_key)

nativegate/templates/__init__.py

@@ -0,0 +1,20 @@
+"""Files that are shipped verbatim and rendered into a generated service.
+
+A template here is a REAL `.py` file, not a string literal inside a
+generator. That is the whole point: as a string it was invisible to this
+project's own linting, type checking and test suite, so a syntax error or a
+stale reference inside it only surfaced when somebody ran the generated
+service. As a module it is parsed, compiled and checked like any other file.
+
+Rendering is plain textual substitution of the sentinel names below — not
+`str.format`, which would require every literal brace in the template to be
+doubled and so make the file invalid Python again.
+
+The sentinels are chosen to be syntactically valid where they appear
+(`NATIVEGATE_PACKAGE` stands in for a module name, the other two live inside
+string literals), which is why the file compiles on its own. It is not
+*runnable* on its own: `import NATIVEGATE_PACKAGE` resolves only once the
+name has been substituted for a real service package.
+"""
+
+from __future__ import annotations

nativegate/templates/golden_test_template.py

@@ -0,0 +1,248 @@
+# Generated by nativegate. Do not edit by hand — re-run `ngate generate`.
+"""Numerical regression: the answers must not change.
+
+`golden.json` records what every bound entry point returned for a fixed set
+of inputs, the tolerance each entry is held to, and the toolchain the values
+were recorded on. This replays those calls against the currently built
+extension and compares.
+
+A failure here does not necessarily mean a bug — it means the numbers moved.
+Two things move them: the code changed, or the toolchain did. The failure
+message reports the recorded toolchain against this one so you can tell which
+before investigating. Then re-record deliberately with:
+
+    ngate golden record NATIVEGATE_SERVICE_NAME
+
+and review the diff in golden.json like any other change to behaviour.
+"""
+
+import json
+import math
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+import NATIVEGATE_PACKAGE
+
+GOLDEN_PATH = Path(__file__).resolve().parent.parent / "NATIVEGATE_GOLDEN_FILENAME"
+
+
+def _numpy():
+    try:
+        import numpy
+    except ImportError:
+        return None
+    return numpy
+
+
+def _is_number(value):
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _materialise(value):
+    if isinstance(value, dict) and "__struct__" in value:
+        native = getattr(NATIVEGATE_PACKAGE, value["__struct__"])()
+        for name, field in value["fields"].items():
+            setattr(native, name, _materialise(field))
+        return native
+    if isinstance(value, list) and value and all(_is_number(v) for v in value):
+        numpy = _numpy()
+        if numpy is not None:
+            dtype = "int64" if all(isinstance(v, int) for v in value) else "float64"
+            return numpy.array(value, dtype=dtype)
+    return value
+
+
+def _jsonable(value):
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    if hasattr(value, "tolist"):
+        return _jsonable(value.tolist())
+    return {
+        name: _jsonable(getattr(value, name))
+        for name in dir(value)
+        if not name.startswith("_") and not callable(getattr(value, name))
+    }
+
+
+def _invoke(entry):
+    """Return (result, {argument index: value after the call}).
+
+    A Fortran routine with an `intent(inout)` array argument returns None and
+    writes its answer into the caller's array; comparing only the return value
+    would compare None against None and prove nothing.
+    """
+    arguments = [_materialise(a) for a in entry["arguments"]]
+    if entry["kind"] == "function":
+        target = getattr(NATIVEGATE_PACKAGE, entry["name"])
+    elif entry["kind"] == "static":
+        target = getattr(getattr(NATIVEGATE_PACKAGE, entry["class"]), entry["name"])
+    else:
+        cls = getattr(NATIVEGATE_PACKAGE, entry["class"])
+        instance = cls(*[_materialise(a) for a in entry["constructor_arguments"]])
+        target = getattr(instance, entry["name"])
+    result = _jsonable(target(*arguments))
+    effects = {}
+    for index, (before, after) in enumerate(zip(entry["arguments"], arguments)):
+        if isinstance(before, list):
+            now = _jsonable(after)
+            if now != before:
+                effects[str(index)] = now
+    return result, effects
+
+
+def _tool_version(command):
+    executable = shutil.which(command)
+    if executable is None:
+        return None
+    try:
+        done = subprocess.run(
+            [executable, "--version"], capture_output=True, text=True,
+            timeout=30, check=False,
+        )
+    except OSError:
+        return None
+    lines = (done.stdout or done.stderr or "").strip().splitlines()
+    return lines[0].strip() if lines else None
+
+
+def _environment():
+    """This machine, in the same shape golden.json recorded.
+
+    Source digests are deliberately absent: a deployed service does not ship
+    the native sources, so re-hashing them here is not possible. The recorded
+    digests still say which sources the values came from.
+    """
+    numpy = _numpy()
+    return {
+        "platform": "%s %s" % (platform.system(), platform.release()),
+        "machine": platform.machine(),
+        "python": platform.python_version(),
+        "python_implementation": platform.python_implementation(),
+        "numpy": None if numpy is None else numpy.__version__,
+        "fortran_compiler": _tool_version("gfortran"),
+        "cxx_compiler": _tool_version("clang++") or _tool_version("g++"),
+    }
+
+
+def _toolchain_report(recorded):
+    if not recorded:
+        return "golden.json records no provenance, so a toolchain change cannot be ruled out."
+    current = _environment()
+    moved = [
+        "  %s: recorded %r, now %r" % (key, recorded.get(key), value)
+        for key, value in current.items()
+        if key in recorded and recorded[key] != value
+    ]
+    if not moved:
+        return (
+            "The toolchain matches what golden.json recorded, so this is a change "
+            "in behaviour, not a platform difference."
+        )
+    return (
+        "The toolchain ALSO changed since these values were recorded. A platform "
+        "difference looks exactly like a regression — rule it out first:\n"
+        + "\n".join(moved)
+    )
+
+
+def _close(expected, actual, rtol, atol):
+    if isinstance(expected, bool) or isinstance(actual, bool):
+        return expected == actual
+    if isinstance(expected, (int, float)) and isinstance(actual, (int, float)):
+        if math.isnan(expected) and math.isnan(actual):
+            return True
+        return math.isclose(expected, actual, rel_tol=rtol, abs_tol=atol)
+    if isinstance(expected, list) and isinstance(actual, list):
+        return len(expected) == len(actual) and all(
+            _close(e, a, rtol, atol) for e, a in zip(expected, actual)
+        )
+    if isinstance(expected, dict) and isinstance(actual, dict):
+        return expected.keys() == actual.keys() and all(
+            _close(expected[k], actual[k], rtol, atol) for k in expected
+        )
+    return expected == actual
+
+
+def _document():
+    if not GOLDEN_PATH.exists():
+        pytest.skip(
+            f"no {GOLDEN_PATH.name} recorded yet — run `ngate golden record NATIVEGATE_SERVICE_NAME`"
+        )
+    return json.loads(GOLDEN_PATH.read_text())
+
+
+def test_golden_values_are_unchanged():
+    document = _document()
+    fallback = document.get("tolerance") or {}
+
+    differences = []
+    for key, entry in (document.get("entries") or {}).items():
+        # Per entry, not one hidden global: a routine that terminates on its
+        # own convergence tolerance cannot be held to the same number as a
+        # closed-form correlation, and saying so in the file is honest where
+        # loosening every entry to match the worst one is not.
+        own = entry.get("tolerance") or {}
+        rtol = own.get("rtol", fallback.get("rtol", 1e-9))
+        atol = own.get("atol", fallback.get("atol", 1e-12))
+        try:
+            actual, effects = _invoke(entry)
+        except Exception as exc:  # noqa: BLE001
+            differences.append(f"{key}: recorded, but this build cannot call it — {exc}")
+            continue
+        expected = entry.get("result")
+        if not _close(expected, actual, rtol, atol):
+            differences.append(
+                f"{key}: expected {expected!r}, got {actual!r} (rtol={rtol}, atol={atol})"
+            )
+        for index, was in (entry.get("argument_effects") or {}).items():
+            if index not in effects:
+                differences.append(
+                    f"{key}: argument {index} was written in place when recorded, "
+                    "and this build does not write it"
+                )
+            elif not _close(was, effects[index], rtol, atol):
+                differences.append(
+                    f"{key}: argument {index} after the call: expected {was!r}, "
+                    f"got {effects[index]!r}"
+                )
+
+    assert not differences, (
+        "numerical regression:\n  "
+        + "\n  ".join(differences)
+        + "\n\n"
+        + _toolchain_report(document.get("provenance"))
+    )
+
+
+def test_golden_file_covers_the_api():
+    # A golden file that records two of forty entry points passes every run
+    # and proves almost nothing. This asserts only that *something* is
+    # covered; the skip reasons in the file say what is not.
+    document = _document()
+    assert document.get("entries"), (
+        "golden.json records no entry points at all — see its 'skipped' block "
+        "for why, then re-record with `ngate golden record NATIVEGATE_SERVICE_NAME`"
+    )
+
+
+def test_golden_file_records_the_toolchain_it_was_recorded_on():
+    # Without this, a failure above cannot distinguish a regression from a
+    # different compiler — and the documented remedy (re-record) would erase
+    # the only evidence of which it was.
+    document = _document()
+    recorded = document.get("provenance") or {}
+    missing = [
+        field
+        for field in ("platform", "machine", "python", "sources")
+        if not recorded.get(field)
+    ]
+    assert not missing, (
+        "golden.json is missing provenance %r — re-record with "
+        "`ngate golden record NATIVEGATE_SERVICE_NAME` to capture it" % missing
+    )