nodepyx 1.0.0

package/dist/types/TypeGenerator.js

@@ -0,0 +1,372 @@
+"use strict";
+/**
+ * nodepyx — TypeGenerator
+ * Generates TypeScript .d.ts stub files from Python module introspection.
+ *
+ * Flow:
+ *   1. Check StubCache — return cached stub if fresh.
+ *   2. Run Python introspection via addon.runPythonCode()
+ *      (executes type_inspector.py in the embedded Python runtime).
+ *   3. Parse the JSON introspection result.
+ *   4. Generate .d.ts content using PythonTypeMapper.
+ *   5. Store in StubCache.
+ *   6. Return type info array (PyTypeInfo[]).
+ *
+ * Generated stubs are compatible with TypeScript LSP — they provide
+ * real autocomplete inside editors without running Python.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeGenerator = void 0;
+const path = __importStar(require("path"));
+const PythonTypeMapper_1 = require("./PythonTypeMapper");
+const StubCache_1 = require("./StubCache");
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('TypeGenerator');
+/**
+ * TypeGenerator — generates TypeScript type stubs from Python modules.
+ *
+ * @example
+ * ```typescript
+ * const gen = new TypeGenerator({ stubsDir: './.nodepyx/stubs' });
+ *
+ * // Generate stub (uses cache if available)
+ * const dts = await gen.generateStub('pandas');
+ *
+ * // Access parsed type info
+ * const info = await gen.inspectModule('pandas');
+ * console.log(info.classes.map(c => c.name));
+ * ```
+ */
+class TypeGenerator {
+    _options;
+    _cache;
+    constructor(options = {}) {
+        this._options = {
+            stubsDir: options.stubsDir ?? path.join(process.cwd(), '.nodepyx', 'stubs'),
+            nodepyxVersion: options.nodepyxVersion ?? '1.0.0',
+            strictTypes: options.strictTypes ?? false,
+            maxMembersPerClass: options.maxMembersPerClass ?? 200,
+            includePrivate: options.includePrivate ?? false,
+            includeInherited: options.includeInherited ?? false,
+        };
+        this._cache = new StubCache_1.StubCache({
+            stubsDir: this._options.stubsDir,
+            nodepyxVersion: this._options.nodepyxVersion,
+        });
+        // Pre-populate cache with bundled stubs for common libraries
+        this._cache.initPrebuilts();
+    }
+    // ─── Public API ──────────────────────────────────────────────────────────
+    /**
+     * Generate (or return cached) TypeScript stub for a Python module.
+     * Returns the .d.ts content as a string.
+     */
+    async generateStub(moduleName, inspection, libVersion) {
+        // ── Cache check ──────────────────────────────────────────────────────
+        const cached = this._cache.get(moduleName, libVersion);
+        if (cached) {
+            logger.debug(`TypeGenerator: cache hit for '${moduleName}'`);
+            return cached;
+        }
+        logger.info(`TypeGenerator: generating stub for '${moduleName}'`);
+        if (inspection.error) {
+            logger.warn(`TypeGenerator: introspection error for '${moduleName}': ${inspection.error}`);
+            const fallback = this._generateFallbackStub(moduleName, inspection.error);
+            this._cache.set(moduleName, fallback, { libVersion });
+            return fallback;
+        }
+        const dts = this._generateDTS(moduleName, inspection);
+        this._cache.set(moduleName, dts, { libVersion });
+        return dts;
+    }
+    /**
+     * Parse raw introspection JSON from Python into typed structures.
+     */
+    parseInspection(raw) {
+        return {
+            name: raw.name,
+            file: raw.file,
+            docstring: raw.docstring ?? '',
+            version: raw.version,
+            functions: (raw.functions ?? []).map(f => this._parseCallable(f)),
+            classes: (raw.classes ?? []).map(c => this._parseClass(c)),
+            constants: (raw.constants ?? []).map(m => this._parseMember(m)),
+            submodules: raw.submodules ?? [],
+        };
+    }
+    /**
+     * Return the StubCache instance.
+     */
+    get cache() {
+        return this._cache;
+    }
+    // ─── DTS Generation ───────────────────────────────────────────────────────
+    _generateDTS(moduleName, raw) {
+        const mapper = new PythonTypeMapper_1.PythonTypeMapper({
+            moduleName,
+            strict: this._options.strictTypes,
+            knownClasses: new Set((raw.classes ?? []).map(c => c.name)),
+        });
+        const lines = [];
+        // ── File header ──────────────────────────────────────────────────────
+        lines.push(`// =============================================================`);
+        lines.push(`// nodepyx — Auto-generated TypeScript stub`);
+        lines.push(`// Module : ${moduleName}`);
+        if (raw.version) {
+            lines.push(`// Version: ${raw.version}`);
+        }
+        lines.push(`// Generated: ${new Date().toISOString()}`);
+        lines.push(`// DO NOT EDIT — regenerate with: npx nodepyx generate-stubs ${moduleName}`);
+        lines.push(`// =============================================================`);
+        lines.push(``);
+        // ── Shared type imports ───────────────────────────────────────────────
+        lines.push(`import type { PyProxy, DataFrameResult, SeriesResult } from 'nodepyx';`);
+        lines.push(``);
+        // ── Module declaration ────────────────────────────────────────────────
+        lines.push(`declare module 'nodepyx/${moduleName}' {`);
+        lines.push(``);
+        // Module docstring
+        if (raw.docstring) {
+            lines.push(...this._docComment(raw.docstring, 2));
+        }
+        // ── Constants ────────────────────────────────────────────────────────
+        for (const constant of raw.constants ?? []) {
+            if (!this._options.includePrivate && constant.name.startsWith('_')) {
+                continue;
+            }
+            if (constant.docstring) {
+                lines.push(...this._docComment(constant.docstring, 2));
+            }
+            const tsType = mapper.map(constant.type ?? 'Any');
+            lines.push(`  export const ${constant.name}: ${tsType};`);
+        }
+        if ((raw.constants ?? []).length > 0) {
+            lines.push(``);
+        }
+        // ── Top-level functions ───────────────────────────────────────────────
+        for (const fn of raw.functions ?? []) {
+            if (!this._options.includePrivate && fn.name.startsWith('_')) {
+                continue;
+            }
+            lines.push(...this._functionDecl(fn, mapper, 2, 'export function'));
+            lines.push(``);
+        }
+        // ── Classes ───────────────────────────────────────────────────────────
+        for (const cls of raw.classes ?? []) {
+            if (!this._options.includePrivate && cls.name.startsWith('_')) {
+                continue;
+            }
+            lines.push(...this._classDecl(cls, mapper));
+            lines.push(``);
+        }
+        // ── Sub-module re-exports ─────────────────────────────────────────────
+        for (const sub of raw.submodules ?? []) {
+            lines.push(`  export const ${sub}: PyProxy;`);
+        }
+        lines.push(`}`);
+        lines.push(``);
+        return lines.join('\n');
+    }
+    _functionDecl(fn, mapper, indent, prefix) {
+        const pad = ' '.repeat(indent);
+        const lines = [];
+        if (fn.docstring) {
+            lines.push(...this._docComment(fn.docstring, indent));
+        }
+        const params = (fn.parameters ?? [])
+            .filter(p => p.name !== 'self' && p.name !== 'cls')
+            .filter(p => this._options.includePrivate || !p.name.startsWith('_'))
+            .slice(0, 30) // sanity cap
+            .map(p => this._paramDecl(p, mapper));
+        const retType = (0, PythonTypeMapper_1.mapReturnType)(fn.return_type ?? fn.return_annotation ?? 'None', { strict: this._options.strictTypes });
+        lines.push(`${pad}${prefix} ${fn.name}(${params.join(', ')}): ${retType};`);
+        return lines;
+    }
+    _paramDecl(p, mapper) {
+        const name = p.name;
+        const raw = p.type ?? p.annotation ?? 'Any';
+        const isOptional = p.optional ?? p.has_default ?? false;
+        const isVarArgs = p.kind === 'var_positional';
+        const isKwArgs = p.kind === 'var_keyword';
+        const tsType = mapper.map(raw);
+        if (isVarArgs) {
+            return `...${name}: Array<${tsType}>`;
+        }
+        if (isKwArgs) {
+            return `${name}?: Record<string, ${tsType}>`;
+        }
+        if (isOptional) {
+            return `${name}?: ${tsType} | null`;
+        }
+        return `${name}: ${tsType}`;
+    }
+    _classDecl(cls, mapper) {
+        const lines = [];
+        const pad = '  ';
+        if (cls.docstring) {
+            lines.push(...this._docComment(cls.docstring, 2));
+        }
+        const bases = (cls.bases ?? [])
+            .filter(b => b !== 'object')
+            .map(b => mapper.map(b))
+            .join(', ');
+        lines.push(`${pad}export class ${cls.name}${bases ? ` extends ${bases}` : ''} {`);
+        // Constructor
+        const initMethod = (cls.methods ?? []).find(m => m.name === '__init__');
+        if (initMethod) {
+            const ctorParams = (initMethod.parameters ?? [])
+                .filter(p => p.name !== 'self')
+                .map(p => this._paramDecl(p, mapper));
+            lines.push(`${pad}  constructor(${ctorParams.join(', ')});`);
+        }
+        else {
+            lines.push(`${pad}  constructor(...args: unknown[]);`);
+        }
+        // Properties
+        const allProps = [
+            ...(cls.properties ?? []),
+            ...(cls.members ?? []).filter(m => !m.name.startsWith('__')),
+        ].slice(0, this._options.maxMembersPerClass);
+        for (const prop of allProps) {
+            if (!this._options.includePrivate && prop.name.startsWith('_')) {
+                continue;
+            }
+            const tsType = mapper.map(prop.type ?? 'Any');
+            const ro = prop.read_only ? 'readonly ' : '';
+            lines.push(`${pad}  ${ro}${prop.name}: Promise<${tsType}>;`);
+        }
+        // Methods
+        const allMethods = [
+            ...(cls.methods ?? []).filter(m => m.name !== '__init__'),
+            ...(cls.static_methods ?? []),
+            ...(cls.class_methods ?? []),
+        ].slice(0, this._options.maxMembersPerClass);
+        for (const method of allMethods) {
+            if (!this._options.includePrivate && method.name.startsWith('_')) {
+                if (!['__len__', '__str__', '__repr__', '__iter__'].includes(method.name)) {
+                    continue;
+                }
+            }
+            if (method.docstring) {
+                lines.push(...this._docComment(method.docstring, 4));
+            }
+            const isStatic = (cls.static_methods ?? []).some(s => s.name === method.name);
+            const prefix = isStatic ? 'static ' : '';
+            const params = (method.parameters ?? [])
+                .filter(p => p.name !== 'self' && p.name !== 'cls')
+                .slice(0, 20)
+                .map(p => this._paramDecl(p, mapper));
+            const retType = (0, PythonTypeMapper_1.mapReturnType)(method.return_type ?? method.return_annotation ?? 'None', { strict: this._options.strictTypes });
+            lines.push(`${pad}  ${prefix}${method.name}(${params.join(', ')}): ${retType};`);
+        }
+        lines.push(`${pad}  [key: string]: unknown;`);
+        lines.push(`${pad}}`);
+        return lines;
+    }
+    _generateFallbackStub(moduleName, error) {
+        return [
+            `// nodepyx — Fallback stub for '${moduleName}'`,
+            `// Introspection error: ${error}`,
+            `// Install the module to get proper types.`,
+            ``,
+            `declare module 'nodepyx/${moduleName}' {`,
+            `  export const [key: string]: unknown;`,
+            `}`,
+            ``,
+        ].join('\n');
+    }
+    // ─── Parsing helpers ──────────────────────────────────────────────────────
+    _parseCallable(raw) {
+        return {
+            name: raw.name,
+            qualName: raw.qual_name ?? raw.name,
+            docstring: raw.docstring ?? '',
+            parameters: (raw.parameters ?? []).map(p => this._parseParam(p)),
+            returnType: raw.return_type ?? raw.return_annotation ?? 'None',
+            isMethod: raw.is_method ?? false,
+            isClassMethod: raw.is_class_method ?? false,
+            isStaticMethod: raw.is_static_method ?? false,
+            isCoroutine: raw.is_coroutine ?? false,
+            isGenerator: raw.is_generator ?? false,
+        };
+    }
+    _parseParam(raw) {
+        return {
+            name: raw.name,
+            type: raw.type ?? raw.annotation ?? 'Any',
+            optional: raw.optional ?? raw.has_default ?? false,
+            hasDefault: raw.has_default ?? false,
+            defaultValue: raw.default,
+            kind: raw.kind ?? 'positional_or_keyword',
+        };
+    }
+    _parseClass(raw) {
+        return {
+            name: raw.name,
+            qualName: raw.qual_name ?? raw.name,
+            docstring: raw.docstring ?? '',
+            bases: raw.bases ?? [],
+            members: (raw.members ?? []).map(m => this._parseMember(m)),
+            methods: (raw.methods ?? []).map(f => this._parseCallable(f)),
+            properties: (raw.properties ?? []).map(m => this._parseMember(m)),
+            classMethods: (raw.class_methods ?? []).map(f => this._parseCallable(f)),
+            staticMethods: (raw.static_methods ?? []).map(f => this._parseCallable(f)),
+        };
+    }
+    _parseMember(raw) {
+        return {
+            name: raw.name,
+            type: raw.type ?? 'Any',
+            isReadOnly: raw.read_only ?? false,
+            docstring: raw.docstring,
+        };
+    }
+    // ─── JSDoc helpers ─────────────────────────────────────────────────────────
+    _docComment(docstring, indent) {
+        const pad = ' '.repeat(indent);
+        const lines = docstring.split('\n').slice(0, 8); // cap at 8 lines
+        if (lines.length === 1) {
+            return [`${pad}/** ${lines[0].trim()} */`];
+        }
+        return [
+            `${pad}/**`,
+            ...lines.map(l => `${pad} * ${l.trim()}`),
+            `${pad} */`,
+        ];
+    }
+}
+exports.TypeGenerator = TypeGenerator;
+//# sourceMappingURL=TypeGenerator.js.map

package/dist/types/TypeGenerator.js.map

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

package/dist/types/addon.d.ts

@@ -0,0 +1,114 @@
+/**
+ * nodepyx — Native Addon TypeScript Interface
+ * Type declarations for the C++ N-API addon.
+ * These map exactly to the exported functions in nodepyx_addon.cpp.
+ */
+import type { SerializedValue, PyCallResult, PyIteratorNext, PyTypeInfo, AttributePath } from './python';
+export interface AddonInitOptions {
+    /** Path to Python home directory */
+    pythonHome: string;
+    /** Path to Python executable */
+    pythonExecutable: string;
+    /** Thread pool size */
+    threadPoolSize: number;
+    /** Max thread queue size */
+    maxQueueSize: number;
+    /** GIL release interval (microseconds) */
+    gilReleaseInterval: number;
+    /** Call timeout (milliseconds) */
+    callTimeout: number;
+    /** Additional Python sys.path entries */
+    pythonPathExtra: string[];
+    /** Environment variables */
+    env: Record<string, string>;
+    /** Enable profiling */
+    enableProfiling: boolean;
+}
+export interface AddonImportResult {
+    objectId: number;
+    success: boolean;
+    error?: string;
+}
+export interface AddonAttributeResult {
+    success: boolean;
+    value?: SerializedValue;
+    objectId?: number;
+    isCallable: boolean;
+    isObject: boolean;
+    error?: string;
+}
+export interface AddonCallOptions {
+    /** Positional arguments */
+    args: SerializedValue[];
+    /** Keyword arguments */
+    kwargs: Record<string, SerializedValue>;
+    /** Call timeout override (ms) */
+    timeout?: number;
+}
+export interface AddonIteratorResult {
+    iteratorId: number;
+    success: boolean;
+    error?: string;
+}
+export interface AddonMemoryStats {
+    pythonHeapBytes: number;
+    pythonHeapPeakBytes: number;
+    trackedObjects: number;
+    pendingCallbacks: number;
+    threadPoolActive: number;
+    threadPoolQueued: number;
+}
+export interface AddonProfilingReport {
+    totalCalls: number;
+    totalTimeMs: number;
+    avgCallTimeMs: number;
+    peakCallTimeMs: number;
+    callsByModule: Record<string, number>;
+    callsByFunction: Record<string, number>;
+}
+/**
+ * The full interface of the compiled C++ addon module.
+ * All async methods return Promises (resolved on libuv callback).
+ */
+export interface NativeAddon {
+    initializePython(options: AddonInitOptions): Promise<void>;
+    finalizePython(): Promise<void>;
+    isInitialized(): boolean;
+    importModule(moduleName: string): Promise<AddonImportResult>;
+    reloadModule(objectId: number): Promise<AddonImportResult>;
+    getAttribute(objectId: number, name: string): Promise<AddonAttributeResult>;
+    getAttributePath(objectId: number, path: AttributePath): Promise<AddonAttributeResult>;
+    setAttribute(objectId: number, name: string, value: SerializedValue): Promise<boolean>;
+    hasAttribute(objectId: number, name: string): Promise<boolean>;
+    deleteAttribute(objectId: number, name: string): Promise<boolean>;
+    callFunction(objectId: number, path: AttributePath, options: AddonCallOptions): Promise<PyCallResult>;
+    callMethod(objectId: number, methodName: string, options: AddonCallOptions): Promise<PyCallResult>;
+    getTypeInfo(objectId: number): Promise<PyTypeInfo>;
+    getObjectValue(objectId: number): Promise<SerializedValue>;
+    getObjectRepr(objectId: number): Promise<string>;
+    getObjectLength(objectId: number): Promise<number>;
+    getObjectKeys(objectId: number): Promise<string[]>;
+    createIterator(objectId: number, path: AttributePath): Promise<AddonIteratorResult>;
+    iteratorNext(iteratorId: number): Promise<PyIteratorNext>;
+    destroyIterator(iteratorId: number): Promise<void>;
+    runPythonCode(code: string, globals?: SerializedValue): Promise<SerializedValue>;
+    runPythonFile(filePath: string): Promise<SerializedValue>;
+    evalPython(expression: string): Promise<SerializedValue>;
+    incRef(objectId: number): void;
+    decRef(objectId: number): void;
+    collectGarbage(): Promise<void>;
+    getMemoryStats(): AddonMemoryStats;
+    getProfilingReport(): AddonProfilingReport;
+    resetProfilingStats(): void;
+    setThreadPoolSize(size: number): Promise<void>;
+    getThreadPoolStats(): {
+        active: number;
+        queued: number;
+        total: number;
+    };
+}
+/**
+ * Loads the native addon, trying prebuilds first then build directory.
+ */
+export declare function loadNativeAddon(): NativeAddon;
+//# sourceMappingURL=addon.d.ts.map

package/dist/types/addon.d.ts.map

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

package/dist/types/addon.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * nodepyx — Native Addon TypeScript Interface
+ * Type declarations for the C++ N-API addon.
+ * These map exactly to the exported functions in nodepyx_addon.cpp.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadNativeAddon = loadNativeAddon;
+/**
+ * Loads the native addon, trying prebuilds first then build directory.
+ */
+function loadNativeAddon() {
+    // Try prebuilt binary first (faster, no build tools needed)
+    try {
+        // node-gyp-build handles platform/arch detection automatically
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const build = require('node-gyp-build');
+        return build(__dirname + '/../../');
+    }
+    catch {
+        // Fall back to explicit build path
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            return require('../../build/Release/nodepyx_addon.node');
+        }
+        catch {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            return require('../../build/Debug/nodepyx_addon.node');
+        }
+    }
+}
+//# sourceMappingURL=addon.js.map

package/dist/types/addon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon.js","sourceRoot":"","sources":["../../src/types/addon.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAmJH,0CAiBC;AApBD;;GAEG;AACH,SAAgB,eAAe;IAC7B,4DAA4D;IAC5D,IAAI,CAAC;QACH,+DAA+D;QAC/D,8DAA8D;QAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;QACxC,OAAO,KAAK,CAAC,SAAS,GAAG,SAAS,CAAgB,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,mCAAmC;QACnC,IAAI,CAAC;YACH,8DAA8D;YAC9D,OAAO,OAAO,CAAC,wCAAwC,CAAgB,CAAC;QAC1E,CAAC;QAAC,MAAM,CAAC;YACP,8DAA8D;YAC9D,OAAO,OAAO,CAAC,sCAAsC,CAAgB,CAAC;QACxE,CAAC;IACH,CAAC;AACH,CAAC"}