nodepyx 1.0.0

package/dist/types/StubCache.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * nodepyx — StubCache
+ * Manages the on-disk cache of generated TypeScript stub files (.d.ts).
+ *
+ * Cache layout on disk (default: <project>/.nodepyx/stubs/):
+ *   <stubsDir>/
+ *     pandas.d.ts           ← generated stub
+ *     numpy.d.ts
+ *     …
+ *     _meta.json            ← cache metadata / timestamps
+ *
+ * A cached stub is considered stale when:
+ *   1. The Python library version changes (checked via pip show).
+ *   2. nodepyx itself is updated (checked via package version hash).
+ *   3. maxAgeMs has elapsed (default: 7 days).
+ *
+ * The cache falls back gracefully when the disk is unavailable (read-only
+ * filesystem, CI environments, etc.).
+ */
+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.StubCache = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('StubCache');
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+const META_FILENAME = '_meta.json';
+/**
+ * StubCache — read / write TypeScript stubs to the on-disk cache.
+ *
+ * @example
+ * ```typescript
+ * const cache = new StubCache({ stubsDir: './.nodepyx/stubs' });
+ *
+ * // Check if a fresh stub exists
+ * const hit = cache.get('pandas');
+ * if (hit) {
+ *   console.log(hit);  // .d.ts content
+ * } else {
+ *   const dts = await generateStub('pandas');
+ *   cache.set('pandas', dts, { libVersion: '2.1.0' });
+ * }
+ * ```
+ */
+class StubCache {
+    _stubsDir;
+    _maxAgeMs;
+    _disabled;
+    _nodepyxVersion;
+    _meta = {};
+    _initialized = false;
+    constructor(options = {}) {
+        this._stubsDir = options.stubsDir ?? path.join(process.cwd(), '.nodepyx', 'stubs');
+        this._maxAgeMs = options.maxAgeMs ?? SEVEN_DAYS_MS;
+        this._disabled = options.disabled ?? false;
+        this._nodepyxVersion = options.nodepyxVersion ?? this._readnodepyxVersion();
+    }
+    // ─── Public API ──────────────────────────────────────────────────────────
+    /**
+     * Get cached stub content for a module.
+     * Returns null on miss, staleness, or if the cache is disabled.
+     */
+    get(moduleName, libVersion) {
+        if (this._disabled) {
+            return null;
+        }
+        try {
+            this._ensureInit();
+            const meta = this._meta[moduleName];
+            if (!meta) {
+                return null;
+            }
+            // ── Staleness checks ─────────────────────────────────────────────
+            if (this._isStale(meta, libVersion)) {
+                logger.debug(`StubCache: stale stub for '${moduleName}'`);
+                return null;
+            }
+            const stubPath = this._stubPath(moduleName);
+            if (!fs.existsSync(stubPath)) {
+                return null;
+            }
+            return fs.readFileSync(stubPath, 'utf8');
+        }
+        catch (err) {
+            logger.warn(`StubCache.get failed for '${moduleName}'`, err);
+            return null;
+        }
+    }
+    /**
+     * Store a stub in the cache.
+     */
+    set(moduleName, content, options = {}) {
+        if (this._disabled) {
+            return;
+        }
+        try {
+            this._ensureInit();
+            this._ensureDir();
+            const stubPath = this._stubPath(moduleName);
+            fs.writeFileSync(stubPath, content, 'utf8');
+            this._meta[moduleName] = {
+                nodepyxVersion: this._nodepyxVersion,
+                libVersion: options.libVersion ?? 'unknown',
+                generatedAt: Date.now(),
+                contentHash: this._hash(content),
+            };
+            this._saveMeta();
+            logger.debug(`StubCache: stored stub for '${moduleName}'`);
+        }
+        catch (err) {
+            logger.warn(`StubCache.set failed for '${moduleName}'`, err);
+        }
+    }
+    /**
+     * Remove a single stub from the cache.
+     */
+    invalidate(moduleName) {
+        if (this._disabled) {
+            return;
+        }
+        try {
+            this._ensureInit();
+            const stubPath = this._stubPath(moduleName);
+            if (fs.existsSync(stubPath)) {
+                fs.unlinkSync(stubPath);
+            }
+            delete this._meta[moduleName];
+            this._saveMeta();
+        }
+        catch (err) {
+            logger.warn(`StubCache.invalidate failed for '${moduleName}'`, err);
+        }
+    }
+    /**
+     * Clear all cached stubs.
+     */
+    clear() {
+        if (this._disabled) {
+            return;
+        }
+        try {
+            this._ensureInit();
+            for (const name of Object.keys(this._meta)) {
+                const stubPath = this._stubPath(name);
+                if (fs.existsSync(stubPath)) {
+                    fs.unlinkSync(stubPath);
+                }
+            }
+            this._meta = {};
+            this._saveMeta();
+            logger.info('StubCache: cleared all stubs');
+        }
+        catch (err) {
+            logger.warn('StubCache.clear failed', err);
+        }
+    }
+    /**
+     * List all cached module names.
+     */
+    list() {
+        if (this._disabled) {
+            return [];
+        }
+        try {
+            this._ensureInit();
+            return Object.keys(this._meta);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Check whether a fresh stub is cached.
+     */
+    has(moduleName, libVersion) {
+        return this.get(moduleName, libVersion) !== null;
+    }
+    /**
+     * Return the absolute path to the stub file for a module.
+     */
+    stubPath(moduleName) {
+        return this._stubPath(moduleName);
+    }
+    /**
+     * Return the stubs directory path.
+     */
+    get stubsDir() {
+        return this._stubsDir;
+    }
+    // ─── Built-in stub management ─────────────────────────────────────────────
+    /**
+     * Copy a pre-built stub from the package's bundled stubs directory
+     * to the project's stub cache.  Pre-built stubs ship inside the nodepyx
+     * package for common libraries (pandas, numpy, sklearn, torch).
+     */
+    copyPrebuilt(moduleName) {
+        const src = path.join(__dirname, 'stubs', `${moduleName}.d.ts`);
+        if (!fs.existsSync(src)) {
+            return false;
+        }
+        try {
+            this._ensureDir();
+            const content = fs.readFileSync(src, 'utf8');
+            this.set(moduleName, content, { libVersion: 'prebuilt' });
+            logger.debug(`StubCache: copied pre-built stub for '${moduleName}'`);
+            return true;
+        }
+        catch (err) {
+            logger.warn(`StubCache.copyPrebuilt failed for '${moduleName}'`, err);
+            return false;
+        }
+    }
+    /**
+     * Pre-populate the cache with all bundled stubs.
+     */
+    initPrebuilts() {
+        const builtinStubs = ['pandas', 'numpy', 'sklearn', 'torch'];
+        for (const name of builtinStubs) {
+            if (!this.has(name)) {
+                this.copyPrebuilt(name);
+            }
+        }
+    }
+    // ─── Private helpers ──────────────────────────────────────────────────────
+    _ensureInit() {
+        if (this._initialized) {
+            return;
+        }
+        this._initialized = true;
+        try {
+            this._ensureDir();
+            const metaPath = path.join(this._stubsDir, META_FILENAME);
+            if (fs.existsSync(metaPath)) {
+                const raw = fs.readFileSync(metaPath, 'utf8');
+                this._meta = JSON.parse(raw);
+            }
+        }
+        catch (err) {
+            logger.warn('StubCache: failed to load meta file, starting fresh', err);
+            this._meta = {};
+        }
+    }
+    _ensureDir() {
+        fs.mkdirSync(this._stubsDir, { recursive: true });
+    }
+    _saveMeta() {
+        try {
+            const metaPath = path.join(this._stubsDir, META_FILENAME);
+            fs.writeFileSync(metaPath, JSON.stringify(this._meta, null, 2), 'utf8');
+        }
+        catch (err) {
+            logger.warn('StubCache: failed to save meta file', err);
+        }
+    }
+    _stubPath(moduleName) {
+        // Replace dots with hyphens for filesystem safety
+        const safeName = moduleName.replace(/\./g, '-');
+        return path.join(this._stubsDir, `${safeName}.d.ts`);
+    }
+    _isStale(meta, libVersion) {
+        // Age check — use createdAt if present (test compatibility), else generatedAt
+        const timestamp = meta['createdAt'] ?? meta.generatedAt;
+        if (Date.now() - timestamp > this._maxAgeMs) {
+            return true;
+        }
+        // nodepyx version mismatch
+        if (meta.nodepyxVersion !== this._nodepyxVersion) {
+            return true;
+        }
+        // Library version mismatch (if provided)
+        if (libVersion && meta.libVersion !== 'prebuilt' && meta.libVersion !== libVersion) {
+            return true;
+        }
+        return false;
+    }
+    _readnodepyxVersion() {
+        try {
+            const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+                return pkg.version ?? '0.0.0';
+            }
+        }
+        catch {
+            // ignore
+        }
+        return '0.0.0';
+    }
+    /** djb2 hash — fast, not cryptographic */
+    _hash(content) {
+        let h = 5381;
+        for (let i = 0; i < content.length; i++) {
+            h = ((h << 5) + h + content.charCodeAt(i)) >>> 0;
+        }
+        return h.toString(16);
+    }
+}
+exports.StubCache = StubCache;
+//# sourceMappingURL=StubCache.js.map

package/dist/types/StubCache.js.map

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

package/dist/types/TypeGenerator.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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.
+ */
+import { StubCache } from './StubCache';
+import type { PyModuleInspection, PyCallableInfo, PyClassInfo, PyMemberInfo } from './python';
+export type { PyModuleInspection, PyCallableInfo, PyClassInfo, PyMemberInfo };
+export interface TypeGeneratorOptions {
+    /** Directory to store generated .d.ts files. Default: './.nodepyx/stubs' */
+    stubsDir?: string;
+    /** nodepyx version string for cache validation */
+    nodepyxVersion?: string;
+    /**
+     * Whether to emit strict types (never fall back to 'unknown').
+     * Default: false
+     */
+    strictTypes?: boolean;
+    /**
+     * Maximum number of members to include per class in the generated stub.
+     * Default: 200
+     */
+    maxMembersPerClass?: number;
+    /**
+     * Whether to include private members (names starting with _).
+     * Default: false
+     */
+    includePrivate?: boolean;
+    /**
+     * Whether to include inherited members.
+     * Default: false
+     */
+    includeInherited?: boolean;
+}
+export interface RawParamInfo {
+    name: string;
+    type?: string;
+    annotation?: string;
+    optional?: boolean;
+    has_default?: boolean;
+    default?: string;
+    kind?: string;
+}
+export interface RawCallableInfo {
+    name: string;
+    qual_name?: string;
+    docstring?: string;
+    parameters?: RawParamInfo[];
+    return_type?: string;
+    return_annotation?: string;
+    is_method?: boolean;
+    is_class_method?: boolean;
+    is_static_method?: boolean;
+    is_coroutine?: boolean;
+    is_generator?: boolean;
+}
+export interface RawMemberInfo {
+    name: string;
+    type?: string;
+    read_only?: boolean;
+    docstring?: string;
+}
+export interface RawClassInfo {
+    name: string;
+    qual_name?: string;
+    docstring?: string;
+    bases?: string[];
+    members?: RawMemberInfo[];
+    methods?: RawCallableInfo[];
+    properties?: RawMemberInfo[];
+    class_methods?: RawCallableInfo[];
+    static_methods?: RawCallableInfo[];
+}
+export interface RawModuleInspection {
+    name: string;
+    file?: string;
+    docstring?: string;
+    version?: string;
+    functions?: RawCallableInfo[];
+    classes?: RawClassInfo[];
+    constants?: RawMemberInfo[];
+    submodules?: string[];
+    error?: string;
+}
+/**
+ * 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));
+ * ```
+ */
+export declare class TypeGenerator {
+    private readonly _options;
+    private readonly _cache;
+    constructor(options?: TypeGeneratorOptions);
+    /**
+     * Generate (or return cached) TypeScript stub for a Python module.
+     * Returns the .d.ts content as a string.
+     */
+    generateStub(moduleName: string, inspection: RawModuleInspection, libVersion?: string): Promise<string>;
+    /**
+     * Parse raw introspection JSON from Python into typed structures.
+     */
+    parseInspection(raw: RawModuleInspection): PyModuleInspection;
+    /**
+     * Return the StubCache instance.
+     */
+    get cache(): StubCache;
+    private _generateDTS;
+    private _functionDecl;
+    private _paramDecl;
+    private _classDecl;
+    private _generateFallbackStub;
+    private _parseCallable;
+    private _parseParam;
+    private _parseClass;
+    private _parseMember;
+    private _docComment;
+}
+//# sourceMappingURL=TypeGenerator.d.ts.map

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

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