nodepyx 1.0.0

package/scripts/build-native.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * nodepyx — Native Build Script
+ * Orchestrates the node-gyp build process with proper error reporting.
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function run(cmd, args, options = {}) {
+  const result = spawnSync(cmd, args, {
+    cwd: ROOT,
+    stdio: 'inherit',
+    ...options,
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`Command failed: ${cmd} ${args.join(' ')} (exit code ${result.status})`);
+  }
+
+  return result;
+}
+
+async function main() {
+  const release = !process.argv.includes('--debug');
+  const args = ['rebuild'];
+
+  if (release) {
+    args.push('--release');
+  } else {
+    args.push('--debug');
+  }
+
+  if (process.argv.includes('--verbose')) {
+    args.push('--verbose');
+  }
+
+  console.log(`[build-native] Building ${release ? 'release' : 'debug'} native addon...`);
+
+  try {
+    run('node-gyp', args);
+  } catch {
+    console.log('[build-native] Trying via npx...');
+    run('npx', ['node-gyp', ...args]);
+  }
+
+  // Verify the build output
+  const buildDir = release ? 'Release' : 'Debug';
+  const addonPath = path.join(ROOT, 'build', buildDir, 'nodepyx_addon.node');
+
+  if (fs.existsSync(addonPath)) {
+    const stat = fs.statSync(addonPath);
+    console.log(`[build-native] ✓ Built: ${path.relative(ROOT, addonPath)} (${(stat.size / 1024).toFixed(1)}KB)`);
+  } else {
+    throw new Error(`Build succeeded but addon not found at: ${addonPath}`);
+  }
+}
+
+main().catch(err => {
+  console.error(`[build-native] ERROR: ${err.message}`);
+  process.exit(1);
+});
+

package/scripts/download-prebuilds.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * nodepyx — Pre-built Binary Downloader
+ * Downloads pre-compiled native addon from GitHub releases.
+ * Falls back to source build if download fails.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const https = require('https');
+const { execSync } = require('child_process');
+const os = require('os');
+
+const ROOT = path.resolve(__dirname, '..');
+const pkg = require(path.join(ROOT, 'package.json'));
+
+const GITHUB_ORG = 'nodepyx';
+const GITHUB_REPO = 'nodepyx';
+const VERSION = pkg.version;
+
+function getPlatformDir() {
+  return `${process.platform}-${process.arch}`;
+}
+
+function getNodeABI() {
+  return `node-v${process.versions.modules}`;
+}
+
+function getDownloadUrl() {
+  const platformDir = getPlatformDir();
+  const nodeABI = getNodeABI();
+  const filename = `nodepyx_addon-${nodeABI}.node`;
+
+  return `https://github.com/${GITHUB_ORG}/${GITHUB_REPO}/releases/download/v${VERSION}/${platformDir}/${filename}`;
+}
+
+function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+
+    https.get(url, { headers: { 'User-Agent': `nodepyx/${VERSION}` } }, (response) => {
+      if (response.statusCode === 302 || response.statusCode === 301) {
+        // Follow redirect
+        file.close();
+        fs.unlinkSync(dest);
+        downloadFile(response.headers.location, dest).then(resolve).catch(reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        file.close();
+        fs.unlinkSync(dest);
+        reject(new Error(`HTTP ${response.statusCode} for ${url}`));
+        return;
+      }
+
+      response.pipe(file);
+      file.on('finish', () => {
+        file.close();
+        resolve();
+      });
+    }).on('error', (err) => {
+      file.close();
+      try { fs.unlinkSync(dest); } catch {}
+      reject(err);
+    });
+  });
+}
+
+async function main() {
+  const platformDir = getPlatformDir();
+  const nodeABI = getNodeABI();
+  const prebuildsDir = path.join(ROOT, 'prebuilds', platformDir);
+  const addonFile = `nodepyx_addon-${nodeABI}.node`;
+  const outputPath = path.join(prebuildsDir, addonFile);
+  const downloadUrl = getDownloadUrl();
+
+  console.log(`[nodepyx] Downloading pre-built binary for ${platformDir} / ${nodeABI}`);
+  console.log(`[nodepyx] URL: ${downloadUrl}`);
+
+  fs.mkdirSync(prebuildsDir, { recursive: true });
+
+  try {
+    await downloadFile(downloadUrl, outputPath);
+    console.log(`[nodepyx] ✓ Downloaded to ${path.relative(ROOT, outputPath)}`);
+  } catch (err) {
+    console.warn(`[nodepyx] Download failed: ${err.message}`);
+    console.warn('[nodepyx] Will build from source instead.');
+    process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(`[nodepyx] Error: ${err.message}`);
+  process.exit(1);
+});
+

package/scripts/generate-stubs.js

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+/**
+ * nodepyx — generate-stubs.js
+ * CLI script to pre-generate TypeScript stubs for Python modules.
+ *
+ * Usage:
+ *   node scripts/generate-stubs.js [modules...]
+ *   node scripts/generate-stubs.js pandas numpy sklearn torch
+ *   node scripts/generate-stubs.js --all           # regenerate all cached
+ *   node scripts/generate-stubs.js --clear         # clear stub cache
+ *   node scripts/generate-stubs.js --list          # list cached stubs
+ *   node scripts/generate-stubs.js --stubs-dir=./custom/path pandas
+ *
+ * When called with no module arguments, generates stubs for the
+ * default set: pandas, numpy, sklearn, torch, matplotlib, scipy.
+ *
+ * This script can run standalone (without nodepyx being fully initialized)
+ * by spawning a Python subprocess to run type_inspector.py.
+ */
+
+'use strict';
+
+const path   = require('path');
+const fs     = require('fs');
+const { execFileSync, spawnSync } = require('child_process');
+
+// ── Parse CLI args ────────────────────────────────────────────────────────
+
+const DEFAULT_MODULES = ['pandas', 'numpy', 'sklearn', 'torch', 'matplotlib', 'scipy'];
+
+const args    = process.argv.slice(2);
+const flags   = new Set(args.filter(a => a.startsWith('--')));
+const modules = args.filter(a => !a.startsWith('--'));
+
+// Parse --stubs-dir=<path>
+let stubsDir = path.join(process.cwd(), '.nodepyx', 'stubs');
+for (const flag of flags) {
+  const match = flag.match(/^--stubs-dir=(.+)$/);
+  if (match) {
+    stubsDir = path.resolve(match[1]);
+    flags.delete(flag);
+  }
+}
+
+const flagClear  = flags.has('--clear');
+const flagList   = flags.has('--list');
+const flagAll    = flags.has('--all');
+const flagHelp   = flags.has('--help') || flags.has('-h');
+
+if (flagHelp) {
+  console.log(`
+nodepyx generate-stubs — Generate TypeScript stubs from Python modules
+
+Usage:
+  node scripts/generate-stubs.js [options] [modules...]
+
+Options:
+  --all              Regenerate all currently cached stubs
+  --clear            Clear the stub cache
+  --list             List all cached stubs
+  --stubs-dir=<dir>  Override stub cache directory (default: ./.nodepyx/stubs)
+  --help, -h         Show this help
+
+Examples:
+  node scripts/generate-stubs.js pandas numpy
+  node scripts/generate-stubs.js --all
+  node scripts/generate-stubs.js --clear
+  node scripts/generate-stubs.js --stubs-dir=./types pandas
+`);
+  process.exit(0);
+}
+
+// ── Locate Python ──────────────────────────────────────────────────────────
+
+function findPython() {
+  const candidates = [
+    process.env.nodepyx_PYTHON,
+    process.env.PYTHON,
+    'python3',
+    'python',
+  ].filter(Boolean);
+
+  for (const cmd of candidates) {
+    try {
+      const result = spawnSync(cmd, ['--version'], { encoding: 'utf8', timeout: 5000 });
+      if (result.status === 0) return cmd;
+    } catch {
+      // ignore
+    }
+  }
+  return null;
+}
+
+// ── Run Python introspection ────────────────────────────────────────────────
+
+const INSPECTOR_PY = path.join(__dirname, '..', 'python', 'type_inspector.py');
+
+function inspectModule(pythonCmd, moduleName) {
+  const result = spawnSync(
+    pythonCmd,
+    [INSPECTOR_PY, moduleName],
+    { encoding: 'utf8', timeout: 30_000 },
+  );
+
+  if (result.status !== 0 || result.stderr) {
+    const err = result.stderr?.trim() || 'Unknown error';
+    return { name: moduleName, error: err };
+  }
+
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return { name: moduleName, error: 'Failed to parse inspector output' };
+  }
+}
+
+// ── TypeScript stub generation (pure JS, no TS compilation needed) ──────────
+
+const BUILTIN_TYPE_MAP = {
+  str: 'string', int: 'number', float: 'number', bool: 'boolean',
+  None: 'null', NoneType: 'null', bytes: 'Uint8Array', bytearray: 'Uint8Array',
+  list: 'unknown[]', tuple: 'readonly unknown[]', dict: 'Record<string, unknown>',
+  set: 'Set<unknown>', frozenset: 'ReadonlySet<unknown>', Any: 'unknown',
+  object: 'PyProxy', type: 'PyProxy', module: 'PyProxy',
+  DataFrame: 'DataFrameResult', Series: 'SeriesResult',
+  ndarray: 'Float64Array | Float32Array | Int32Array | Uint8Array',
+  Tensor: 'Float32Array | Float64Array',
+  Callable: '(...args: unknown[]) => unknown',
+  datetime: 'Date', date: 'Date', Path: 'string',
+  NoReturn: 'never', Never: 'never',
+};
+
+function mapPyType(pyType) {
+  if (!pyType) return 'unknown';
+  const t = pyType.trim();
+  if (BUILTIN_TYPE_MAP[t]) return BUILTIN_TYPE_MAP[t];
+
+  // Optional[X]
+  const optMatch = t.match(/^Optional\[(.+)\]$/i);
+  if (optMatch) return `${mapPyType(optMatch[1])} | null`;
+
+  // List[X] / Sequence[X]
+  const listMatch = t.match(/^(?:List|Sequence|Iterable|Set|FrozenSet)\[(.+)\]$/i);
+  if (listMatch) return `Array<${mapPyType(listMatch[1])}>`;
+
+  // Dict[K, V]
+  const dictMatch = t.match(/^(?:Dict|Mapping)\[(.+),\s*(.+)\]$/i);
+  if (dictMatch) return `Record<${mapPyType(dictMatch[1])}, ${mapPyType(dictMatch[2])}>`;
+
+  // Union[A, B]
+  const unionMatch = t.match(/^Union\[(.+)\]$/i);
+  if (unionMatch) {
+    const parts = splitParams(unionMatch[1]);
+    return parts.map(mapPyType).join(' | ');
+  }
+
+  return 'PyProxy';
+}
+
+function splitParams(str) {
+  const parts = [];
+  let depth = 0, curr = '';
+  for (const ch of str) {
+    if (ch === '[') { depth++; curr += ch; }
+    else if (ch === ']') { depth--; curr += ch; }
+    else if (ch === ',' && depth === 0) { parts.push(curr.trim()); curr = ''; }
+    else { curr += ch; }
+  }
+  if (curr.trim()) parts.push(curr.trim());
+  return parts;
+}
+
+function mapReturnType(pyType) {
+  if (!pyType || pyType === 'None' || pyType === 'NoneType') return 'Promise<void>';
+  return `Promise<${mapPyType(pyType)}>`;
+}
+
+function escape(str) {
+  return (str || '').replace(/\*\//g, '* /').slice(0, 200);
+}
+
+function generateDTS(moduleName, inspection) {
+  if (!inspection || inspection.error) {
+    return [
+      `// nodepyx — Fallback stub for '${moduleName}'`,
+      `// ${inspection?.error || 'Module not available'}`,
+      ``,
+      `declare module 'nodepyx/${moduleName}' {`,
+      `  const [key: string]: unknown;`,
+      `}`,
+      ``,
+    ].join('\n');
+  }
+
+  const lines = [
+    `// =============================================================`,
+    `// nodepyx — Auto-generated TypeScript stub`,
+    `// Module : ${moduleName}`,
+    inspection.version ? `// Version: ${inspection.version}` : null,
+    `// Generated: ${new Date().toISOString()}`,
+    `// DO NOT EDIT — regenerate with: npx nodepyx generate-stubs ${moduleName}`,
+    `// =============================================================`,
+    ``,
+    `import type { PyProxy, DataFrameResult, SeriesResult } from 'nodepyx';`,
+    ``,
+    `declare module 'nodepyx/${moduleName}' {`,
+    ``,
+  ].filter(l => l !== null);
+
+  // Constants
+  for (const c of inspection.constants || []) {
+    if (c.name.startsWith('_')) continue;
+    if (c.docstring) lines.push(`  /** ${escape(c.docstring)} */`);
+    lines.push(`  export const ${c.name}: ${mapPyType(c.type || 'Any')};`);
+  }
+
+  // Functions
+  for (const fn of inspection.functions || []) {
+    if (fn.name.startsWith('_')) continue;
+    if (fn.docstring) lines.push(`  /** ${escape(fn.docstring)} */`);
+    const params = (fn.parameters || [])
+      .filter(p => p.name !== 'self' && p.name !== 'cls')
+      .slice(0, 20)
+      .map(p => {
+        const tsType = mapPyType(p.type || 'Any');
+        if (p.kind === 'var_positional') return `...${p.name}: Array<${tsType}>`;
+        if (p.kind === 'var_keyword')    return `${p.name}?: Record<string, ${tsType}>`;
+        if (p.optional || p.has_default) return `${p.name}?: ${tsType} | null`;
+        return `${p.name}: ${tsType}`;
+      });
+    lines.push(`  export function ${fn.name}(${params.join(', ')}): ${mapReturnType(fn.return_type)};`);
+    lines.push(``);
+  }
+
+  // Classes
+  for (const cls of inspection.classes || []) {
+    if (cls.name.startsWith('_')) continue;
+    if (cls.docstring) lines.push(`  /** ${escape(cls.docstring)} */`);
+    lines.push(`  export class ${cls.name} {`);
+    lines.push(`    constructor(...args: unknown[]);`);
+
+    const props = [...(cls.properties || []), ...(cls.members || [])].slice(0, 100);
+    for (const prop of props) {
+      if (prop.name.startsWith('_')) continue;
+      const ro = prop.read_only ? 'readonly ' : '';
+      lines.push(`    ${ro}${prop.name}: Promise<${mapPyType(prop.type || 'Any')}>;`);
+    }
+
+    const methods = [
+      ...(cls.methods || []).filter(m => m.name !== '__init__'),
+      ...(cls.static_methods || []),
+    ].slice(0, 100);
+
+    for (const m of methods) {
+      if (m.name.startsWith('__') && !['__len__', '__str__', '__iter__'].includes(m.name)) continue;
+      if (m.docstring) lines.push(`    /** ${escape(m.docstring)} */`);
+      const isStatic = (cls.static_methods || []).some(s => s.name === m.name);
+      const params = (m.parameters || [])
+        .filter(p => p.name !== 'self' && p.name !== 'cls')
+        .slice(0, 15)
+        .map(p => {
+          const tsType = mapPyType(p.type || 'Any');
+          if (p.optional || p.has_default) return `${p.name}?: ${tsType} | null`;
+          return `${p.name}: ${tsType}`;
+        });
+      const prefix = isStatic ? 'static ' : '';
+      lines.push(`    ${prefix}${m.name}(${params.join(', ')}): ${mapReturnType(m.return_type)};`);
+    }
+
+    lines.push(`    [key: string]: unknown;`);
+    lines.push(`  }`);
+    lines.push(``);
+  }
+
+  lines.push(`}`);
+  lines.push(``);
+
+  return lines.join('\n');
+}
+
+// ── Stub cache I/O ────────────────────────────────────────────────────────
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function metaPath() {
+  return path.join(stubsDir, '_meta.json');
+}
+
+function loadMeta() {
+  try {
+    if (fs.existsSync(metaPath())) {
+      return JSON.parse(fs.readFileSync(metaPath(), 'utf8'));
+    }
+  } catch { /* ignore */ }
+  return { stubs: {} };
+}
+
+function saveMeta(meta) {
+  fs.writeFileSync(metaPath(), JSON.stringify(meta, null, 2), 'utf8');
+}
+
+function stubFilePath(moduleName) {
+  return path.join(stubsDir, `${moduleName.replace(/\./g, '-')}.d.ts`);
+}
+
+function writeStub(moduleName, content, libVersion) {
+  ensureDir(stubsDir);
+  const fp   = stubFilePath(moduleName);
+  const meta = loadMeta();
+  fs.writeFileSync(fp, content, 'utf8');
+  meta.stubs[moduleName] = {
+    nodepyxVersion: '1.0.0',
+    libVersion: libVersion || 'unknown',
+    generatedAt: Date.now(),
+    contentHash: content.length.toString(16),
+  };
+  saveMeta(meta);
+  return fp;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────
+
+async function main() {
+  const meta = loadMeta();
+
+  if (flagClear) {
+    console.log(`🗑  Clearing stub cache at ${stubsDir}…`);
+    for (const name of Object.keys(meta.stubs)) {
+      const fp = stubFilePath(name);
+      if (fs.existsSync(fp)) fs.unlinkSync(fp);
+    }
+    saveMeta({ stubs: {} });
+    console.log('✅ Cache cleared.');
+    return;
+  }
+
+  if (flagList) {
+    const names = Object.keys(meta.stubs);
+    if (names.length === 0) {
+      console.log('No cached stubs found.');
+    } else {
+      console.log(`Cached stubs in ${stubsDir}:`);
+      for (const [name, info] of Object.entries(meta.stubs)) {
+        const age = Math.round((Date.now() - (info.generatedAt || 0)) / 1000 / 60);
+        console.log(`  • ${name.padEnd(30)} v${info.libVersion}  (${age} min ago)`);
+      }
+    }
+    return;
+  }
+
+  // Determine which modules to process
+  let targetModules;
+  if (flagAll) {
+    targetModules = Object.keys(meta.stubs).length > 0
+      ? Object.keys(meta.stubs)
+      : DEFAULT_MODULES;
+  } else if (modules.length > 0) {
+    targetModules = modules;
+  } else {
+    targetModules = DEFAULT_MODULES;
+  }
+
+  const pythonCmd = findPython();
+  if (!pythonCmd) {
+    console.error('❌ Could not find Python executable. Set nodepyx_PYTHON env var.');
+    process.exit(1);
+  }
+
+  console.log(`🐍 Using Python: ${pythonCmd}`);
+  console.log(`📁 Stubs directory: ${stubsDir}`);
+  console.log(`📦 Modules: ${targetModules.join(', ')}`);
+  console.log('');
+
+  let generated = 0;
+  let errors    = 0;
+
+  for (const moduleName of targetModules) {
+    process.stdout.write(`  Generating ${moduleName}… `);
+
+    const inspection = inspectModule(pythonCmd, moduleName);
+    const libVersion = inspection.version || 'unknown';
+    const dts        = generateDTS(moduleName, inspection);
+    const fp         = writeStub(moduleName, dts, libVersion);
+
+    if (inspection.error) {
+      console.log(`⚠  (fallback stub — ${inspection.error.slice(0, 60)})`);
+      errors++;
+    } else {
+      const lineCount = dts.split('\n').length;
+      console.log(`✅ ${lineCount} lines  →  ${path.relative(process.cwd(), fp)}`);
+      generated++;
+    }
+  }
+
+  console.log('');
+  console.log(`Done: ${generated} generated, ${errors} errors.`);
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err.message);
+  process.exit(1);
+});
+