pynect 0.0.0 → 0.2.1

package/dist/utils/memory-monitor.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * pynect - Memory Monitor
+ * Tracks Python object references, heap usage, and triggers GC when needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryMonitor = void 0;
+const logger_1 = require("./logger");
+const locking_1 = require("./locking");
+class MemoryMonitor {
+    _logger;
+    _addon = null;
+    _snapshots = [];
+    _maxSnapshots = 100;
+    _monitorInterval = null;
+    _thresholds;
+    constructor(thresholds) {
+        this._logger = new logger_1.Logger('MemoryMonitor');
+        this._thresholds = {
+            gcThreshold: this._parseBytes('1GB'),
+            objectWarningCount: 10000,
+            callbackWarningCount: 500,
+            ...thresholds,
+        };
+    }
+    attach(addon) {
+        this._addon = addon;
+    }
+    startMonitoring(intervalMs = 5000) {
+        if (this._monitorInterval) {
+            return;
+        }
+        this._monitorInterval = setInterval(() => {
+            this._checkMemory().catch(err => {
+                this._logger.error('Memory check failed', err);
+            });
+        }, intervalMs);
+        // Don't keep event loop alive
+        if (this._monitorInterval.unref) {
+            this._monitorInterval.unref();
+        }
+        this._logger.debug(`Memory monitoring started (interval: ${intervalMs}ms)`);
+    }
+    stopMonitoring() {
+        if (this._monitorInterval) {
+            clearInterval(this._monitorInterval);
+            this._monitorInterval = null;
+            this._logger.debug('Memory monitoring stopped');
+        }
+    }
+    async takeSnapshot() {
+        const nodeHeap = process.memoryUsage();
+        let pythonStats = { pythonHeapBytes: 0, pythonHeapPeakBytes: 0, trackedObjects: 0, pendingCallbacks: 0 };
+        if (this._addon) {
+            const stats = this._addon.getMemoryStats();
+            pythonStats = {
+                pythonHeapBytes: stats.pythonHeapBytes,
+                pythonHeapPeakBytes: stats.pythonHeapPeakBytes,
+                trackedObjects: stats.trackedObjects,
+                pendingCallbacks: stats.pendingCallbacks,
+            };
+        }
+        const snapshot = {
+            timestamp: Date.now(),
+            ...pythonStats,
+            nodeHeapUsed: nodeHeap.heapUsed,
+            nodeHeapTotal: nodeHeap.heapTotal,
+            nodeExternal: nodeHeap.external,
+        };
+        this._snapshots.push(snapshot);
+        if (this._snapshots.length > this._maxSnapshots) {
+            this._snapshots.shift();
+        }
+        return snapshot;
+    }
+    getSnapshots() {
+        return [...this._snapshots];
+    }
+    getLatestSnapshot() {
+        return this._snapshots[this._snapshots.length - 1] ?? null;
+    }
+    async forceGC() {
+        await (0, locking_1.withPynectLock)({ operation: 'python-gc' }, async () => {
+            if (!this._addon)
+                return;
+            this._logger.debug('Running Python garbage collection...');
+            await this._addon.collectGarbage();
+            this._logger.debug('Python GC completed');
+        }, async () => this._addon !== null, {
+            key: 'pynect-python-gc',
+            name: 'Pynect Python garbage collection',
+            namespace: 'pynect',
+            scope: 'memory',
+        });
+    }
+    async _checkMemory() {
+        const snapshot = await this.takeSnapshot();
+        // Check Python heap threshold
+        if (snapshot.pythonHeapBytes > this._thresholds.gcThreshold) {
+            this._logger.warn(`Python heap (${this._formatBytes(snapshot.pythonHeapBytes)}) exceeded GC threshold ` +
+                `(${this._formatBytes(this._thresholds.gcThreshold)}). Running GC...`);
+            await this.forceGC();
+        }
+        // Check tracked objects
+        if (snapshot.trackedObjects > this._thresholds.objectWarningCount) {
+            this._logger.warn(`High Python object count: ${snapshot.trackedObjects} tracked objects`);
+        }
+        // Check pending callbacks
+        if (snapshot.pendingCallbacks > this._thresholds.callbackWarningCount) {
+            this._logger.warn(`High pending callback count: ${snapshot.pendingCallbacks}`);
+        }
+    }
+    _parseBytes(str) {
+        const match = str.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB|TB)?$/i);
+        if (!match) {
+            return 1_073_741_824;
+        } // 1GB default
+        const value = parseFloat(match[1]);
+        const unit = (match[2] ?? 'B').toUpperCase();
+        const units = {
+            B: 1,
+            KB: 1024,
+            MB: 1024 ** 2,
+            GB: 1024 ** 3,
+            TB: 1024 ** 4,
+        };
+        return Math.floor(value * (units[unit] ?? 1));
+    }
+    _formatBytes(bytes) {
+        if (bytes < 1024) {
+            return `${bytes}B`;
+        }
+        if (bytes < 1024 ** 2) {
+            return `${(bytes / 1024).toFixed(1)}KB`;
+        }
+        if (bytes < 1024 ** 3) {
+            return `${(bytes / 1024 ** 2).toFixed(1)}MB`;
+        }
+        return `${(bytes / 1024 ** 3).toFixed(2)}GB`;
+    }
+}
+exports.MemoryMonitor = MemoryMonitor;
+//# sourceMappingURL=memory-monitor.js.map

package/dist/utils/memory-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-monitor.js","sourceRoot":"","sources":["../../src/utils/memory-monitor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,41 +1,117 @@
 {
   "name": "pynect",
-  "version": "0.0.0",
-  "description": "Typed Python interoperability for Node.js and Bun.",
-  "type": "module",
-  "main": "./index.js",
-  "types": "./index.d.ts",
+  "version": "0.2.1",
+  "packageManager": "bun@1.4.4",
+  "description": "Typed, optionally Pydantic-validated Python calls from Node.js and Bun through embedded CPython.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "import": "./index.js",
-      "default": "./index.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js",
+      "require": "./dist/types/index.js"
     }
   },
+  "bin": {
+    "pynect": "scripts/cli.js"
+  },
   "files": [
-    "index.js",
-    "index.d.ts",
+    "dist/",
+    "prebuilds/",
+    "src/native/",
+    "python/*.py",
+    "scripts/build-native.js",
+    "scripts/cli.js",
+    "scripts/ensure-native.js",
+    "scripts/postinstall.js",
+    "scripts/pyfig.js",
+    "scripts/python-provisioner.js",
+    "scripts/smoke-python-boundary.js",
+    "binding.gyp",
     "README.md",
+    "SECURITY.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "bun run build:ts && bun run build:native",
+    "build:ts": "bun scripts/build-typescript.js",
+    "build:native": "bun scripts/build-native.js",
+    "postinstall": "node scripts/postinstall.js",
+    "release": "bun scripts/release.ts",
+    "test": "bun test",
+    "test:python-boundary": "bun scripts/smoke-python-boundary.js",
+    "codegen": "bun run build:ts && bun scripts/cli.js codegen",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck:release": "tsc --noEmit -p tsconfig.release.json",
+    "verify": "bun run typecheck && bun run typecheck:release && bun test && bun run build && bun run test:python-boundary",
+    "prepack": "bun scripts/prepack.ts"
+  },
   "keywords": [
     "python",
     "nodejs",
     "bun",
     "typescript",
-    "interop"
+    "pydantic",
+    "cpython",
+    "native-addon",
+    "n-api"
   ],
-  "author": "Reggie Bowser and nodepyx contributors",
+  "author": "Reggie Bowser and NodePyX contributors",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/regbo/pyts-bridge.git"
+    "url": "git+https://github.com/regbo/pynect.git"
   },
   "bugs": {
-    "url": "https://github.com/regbo/pyts-bridge/issues"
+    "url": "https://github.com/regbo/pynect/issues"
   },
-  "homepage": "https://github.com/regbo/pyts-bridge#readme",
+  "homepage": "https://github.com/regbo/pynect#readme",
+  "upstream": "https://github.com/Brah-Timo/nodepyx",
   "publishConfig": {
-    "access": "public"
-  }
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.2",
+    "commander": "^14.0.2",
+    "jsonc-parser": "^3.3.1",
+    "loqkit": "^0.0.3",
+    "node-addon-api": "^8.5.0",
+    "node-gyp": "^11.5.0",
+    "node-gyp-build": "^4.8.4",
+    "pacwich": "^0.7.3",
+    "pyfig": "^0.4.0",
+    "semver": "^7.8.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.1",
+    "@types/node": "^24.10.0",
+    "@types/semver": "^7.7.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.2.0"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "binary": {
+    "module_name": "pynect_addon",
+    "module_path": "./prebuilds/{platform}-{arch}"
+  },
+  "gypfile": false
 }

package/prebuilds/darwin-arm64/pynect-prebuild.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "platform": "darwin",
+  "architecture": "arm64",
+  "pythonMajorMinor": "3.12",
+  "pythonLibraryName": "Python",
+  "napi": 8
+}

package/prebuilds/darwin-x64/pynect-prebuild.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "platform": "darwin",
+  "architecture": "x64",
+  "pythonMajorMinor": "3.12",
+  "pythonLibraryName": "Python",
+  "napi": 8
+}

package/prebuilds/linux-arm64/pynect-prebuild.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "platform": "linux",
+  "architecture": "arm64",
+  "pythonMajorMinor": "3.12",
+  "pythonLibraryName": "libpython3.12.so",
+  "napi": 8,
+  "glibc": "2.39"
+}

package/prebuilds/linux-x64/pynect-prebuild.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "platform": "linux",
+  "architecture": "x64",
+  "pythonMajorMinor": "3.12",
+  "pythonLibraryName": "libpython3.12.so",
+  "napi": 8,
+  "glibc": "2.35"
+}

package/prebuilds/win32-arm64/pynect-prebuild.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "platform": "win32",
+  "architecture": "arm64",
+  "pythonMajorMinor": "3.12",
+  "pythonLibraryName": "python312.lib",
+  "napi": 8
+}

package/prebuilds/win32-x64/pynect-prebuild.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "platform": "win32",
+  "architecture": "x64",
+  "pythonMajorMinor": "3.12",
+  "pythonLibraryName": "python312.lib",
+  "napi": 8
+}

package/python/ast_inspector.py

@@ -0,0 +1,248 @@
+"""Static Python module inspection for safe TypeScript declaration generation."""
+
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _annotation(node: ast.expr | None) -> str:
+    if node is None:
+        return "Any"
+    try:
+        return ast.unparse(node).replace("typing.", "")
+    except Exception:
+        return "Any"
+
+
+def _decorator_name(node: ast.expr) -> str:
+    if isinstance(node, ast.Call):
+        return _decorator_name(node.func)
+    if isinstance(node, ast.Attribute):
+        return f"{_decorator_name(node.value)}.{node.attr}".strip(".")
+    if isinstance(node, ast.Name):
+        return node.id
+    return ""
+
+
+def _decorators(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> set[str]:
+    return {_decorator_name(item) for item in node.decorator_list}
+
+
+def _has_decorator(names: set[str], leaf: str) -> bool:
+    return any(name == leaf or name.endswith(f".{leaf}") for name in names)
+
+
+def _default_text(node: ast.expr | None) -> str | None:
+    if node is None:
+        return None
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return None
+
+
+def _parameters(node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[dict[str, Any]]:
+    arguments = node.args
+    positional = [*arguments.posonlyargs, *arguments.args]
+    positional_defaults: list[ast.expr | None] = [None] * (
+        len(positional) - len(arguments.defaults)
+    ) + list(arguments.defaults)
+    result: list[dict[str, Any]] = []
+
+    def add(argument: ast.arg, kind: str, default: ast.expr | None = None) -> None:
+        has_default = default is not None
+        result.append(
+            {
+                "name": argument.arg,
+                "type": _annotation(argument.annotation),
+                "annotation": _annotation(argument.annotation),
+                "optional": has_default or kind in {"var_positional", "var_keyword"},
+                "has_default": has_default,
+                "default": _default_text(default),
+                "kind": kind,
+            }
+        )
+
+    positional_only = len(arguments.posonlyargs)
+    for index, (argument, default) in enumerate(zip(positional, positional_defaults)):
+        kind = "positional_only" if index < positional_only else "positional_or_keyword"
+        add(argument, kind, default)
+    if arguments.vararg is not None:
+        add(arguments.vararg, "var_positional")
+    for argument, default in zip(arguments.kwonlyargs, arguments.kw_defaults):
+        add(argument, "keyword_only", default)
+    if arguments.kwarg is not None:
+        add(arguments.kwarg, "var_keyword")
+    return result
+
+
+def _callable(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    *,
+    qualified_name: str | None = None,
+) -> dict[str, Any]:
+    decorators = _decorators(node)
+    parameters = _parameters(node)
+    return {
+        "name": node.name,
+        "qual_name": qualified_name or node.name,
+        "docstring": ast.get_docstring(node) or "",
+        "parameters": parameters,
+        "return_type": _annotation(node.returns),
+        "is_method": qualified_name is not None,
+        "is_class_method": _has_decorator(decorators, "classmethod"),
+        "is_static_method": _has_decorator(decorators, "staticmethod"),
+        "is_coroutine": isinstance(node, ast.AsyncFunctionDef),
+        "is_generator": any(isinstance(item, (ast.Yield, ast.YieldFrom)) for item in ast.walk(node)),
+        "exported": _has_decorator(decorators, "export"),
+        "excluded": _has_decorator(decorators, "exclude"),
+        "fully_typed": node.returns is not None
+        and all(
+            parameter["type"] != "Any"
+            for parameter in parameters
+            if parameter["name"] not in {"self", "cls"}
+        ),
+    }
+
+
+def _class(node: ast.ClassDef) -> dict[str, Any]:
+    decorators = _decorators(node)
+    result: dict[str, Any] = {
+        "name": node.name,
+        "qual_name": node.name,
+        "docstring": ast.get_docstring(node) or "",
+        "bases": [_annotation(base) for base in node.bases],
+        "members": [],
+        "methods": [],
+        "properties": [],
+        "class_methods": [],
+        "static_methods": [],
+        "exported": _has_decorator(decorators, "export"),
+        "excluded": _has_decorator(decorators, "exclude"),
+        "fully_typed": False,
+    }
+    property_setters: set[str] = set()
+    for item in node.body:
+        if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
+            result["members"].append(
+                {
+                    "name": item.target.id,
+                    "type": _annotation(item.annotation),
+                    "read_only": False,
+                    "docstring": "",
+                    "fully_typed": True,
+                    "exported": False,
+                    "excluded": False,
+                }
+            )
+            continue
+        if not isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        names = _decorators(item)
+        qualified = f"{node.name}.{item.name}"
+        inspected = _callable(item, qualified_name=qualified)
+        if any(name.endswith(".setter") for name in names):
+            property_setters.add(item.name)
+        elif _has_decorator(names, "property"):
+            result["properties"].append(
+                {
+                    "name": item.name,
+                    "type": _annotation(item.returns),
+                    "read_only": True,
+                    "docstring": ast.get_docstring(item) or "",
+                    "fully_typed": item.returns is not None,
+                    "exported": inspected["exported"],
+                    "excluded": inspected["excluded"],
+                }
+            )
+        elif inspected["is_static_method"]:
+            result["static_methods"].append(inspected)
+        elif inspected["is_class_method"]:
+            result["class_methods"].append(inspected)
+        else:
+            result["methods"].append(inspected)
+    for prop in result["properties"]:
+        if prop["name"] in property_setters:
+            prop["read_only"] = False
+    result["fully_typed"] = bool(result["members"]) or any(
+        method["fully_typed"]
+        for key in ("methods", "class_methods", "static_methods")
+        for method in result[key]
+    )
+    return result
+
+
+def _literal_type(node: ast.expr | None) -> str:
+    if isinstance(node, ast.Constant):
+        value = node.value
+        if value is None:
+            return "None"
+        return type(value).__name__
+    if isinstance(node, (ast.List, ast.ListComp)):
+        return "list[Any]"
+    if isinstance(node, (ast.Dict, ast.DictComp)):
+        return "dict[str, Any]"
+    if isinstance(node, (ast.Tuple, ast.GeneratorExp)):
+        return "tuple[Any]"
+    if isinstance(node, (ast.Set, ast.SetComp)):
+        return "set[Any]"
+    return "Any"
+
+
+def inspect_file(file_path: str, module_name: str) -> dict[str, Any]:
+    path = Path(file_path).resolve()
+    source = path.read_text(encoding="utf-8-sig")
+    tree = ast.parse(source, filename=str(path), type_comments=True)
+    result: dict[str, Any] = {
+        "name": module_name,
+        "file": str(path),
+        "docstring": ast.get_docstring(tree) or "",
+        "version": None,
+        "functions": [],
+        "classes": [],
+        "constants": [],
+        "submodules": [],
+        "inspection": "ast",
+    }
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            result["functions"].append(_callable(node))
+        elif isinstance(node, ast.ClassDef):
+            result["classes"].append(_class(node))
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            result["constants"].append(
+                {
+                    "name": node.target.id,
+                    "type": _annotation(node.annotation),
+                    "read_only": True,
+                    "docstring": "",
+                    "fully_typed": True,
+                    "exported": False,
+                    "excluded": False,
+                }
+            )
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if not isinstance(target, ast.Name):
+                    continue
+                if target.id == "__version__" and isinstance(node.value, ast.Constant):
+                    result["version"] = str(node.value.value)
+                result["constants"].append(
+                    {
+                        "name": target.id,
+                        "type": _literal_type(node.value),
+                        "read_only": True,
+                        "docstring": "",
+                        "fully_typed": False,
+                        "exported": False,
+                        "excluded": False,
+                    }
+                )
+    return result
+
+
+def inspect_file_json(file_path: str, module_name: str) -> str:
+    return json.dumps(inspect_file(file_path, module_name), default=str)