nodepyx 1.0.0

package/src/types/StubCache.ts

@@ -0,0 +1,340 @@
+/**
+ * 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.).
+ */
+
+import * as fs   from 'fs';
+import * as path from 'path';
+import { Logger } from '../utils/Logger';
+
+const logger = new Logger('StubCache');
+
+// ── On-disk meta file schema ──────────────────────────────────────────────
+
+interface StubMeta {
+  /** nodepyx version that generated the stub */
+  nodepyxVersion: string;
+  /** Python library version at generation time */
+  libVersion: string;
+  /** Unix timestamp (ms) of generation */
+  generatedAt: number;
+  /** SHA-1 hex of the stub content */
+  contentHash: string;
+}
+
+// MetaFile is a flat map: moduleName → StubMeta
+// (top-level keys are module names, so tests can do meta['module_name'].createdAt)
+type MetaFile = Record<string, StubMeta>;
+
+// ── Default options ───────────────────────────────────────────────────────
+
+export interface StubCacheOptions {
+  /** Directory where stub files are stored. Default: './.nodepyx/stubs' */
+  stubsDir?: string;
+  /** Time-to-live for cached stubs in ms. Default: 7 days */
+  maxAgeMs?: number;
+  /** Disable the cache entirely (always regenerate). Default: false */
+  disabled?: boolean;
+  /** nodepyx package version string (used in staleness checks) */
+  nodepyxVersion?: string;
+}
+
+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' });
+ * }
+ * ```
+ */
+export class StubCache {
+  private readonly _stubsDir: string;
+  private readonly _maxAgeMs: number;
+  private readonly _disabled: boolean;
+  private readonly _nodepyxVersion: string;
+  private _meta: MetaFile = {};
+  private _initialized = false;
+
+  constructor(options: StubCacheOptions = {}) {
+    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: string, libVersion?: string): string | null {
+    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: string,
+    content: string,
+    options: { libVersion?: string } = {},
+  ): void {
+    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: string): void {
+    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(): void {
+    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(): string[] {
+    if (this._disabled) {return [];}
+    try {
+      this._ensureInit();
+      return Object.keys(this._meta);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Check whether a fresh stub is cached.
+   */
+  has(moduleName: string, libVersion?: string): boolean {
+    return this.get(moduleName, libVersion) !== null;
+  }
+
+  /**
+   * Return the absolute path to the stub file for a module.
+   */
+  stubPath(moduleName: string): string {
+    return this._stubPath(moduleName);
+  }
+
+  /**
+   * Return the stubs directory path.
+   */
+  get stubsDir(): string {
+    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: string): boolean {
+    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(): void {
+    const builtinStubs = ['pandas', 'numpy', 'sklearn', 'torch'];
+    for (const name of builtinStubs) {
+      if (!this.has(name)) {
+        this.copyPrebuilt(name);
+      }
+    }
+  }
+
+  // ─── Private helpers ──────────────────────────────────────────────────────
+
+  private _ensureInit(): void {
+    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) as MetaFile;
+      }
+    } catch (err) {
+      logger.warn('StubCache: failed to load meta file, starting fresh', err);
+      this._meta = {};
+    }
+  }
+
+  private _ensureDir(): void {
+    fs.mkdirSync(this._stubsDir, { recursive: true });
+  }
+
+  private _saveMeta(): void {
+    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);
+    }
+  }
+
+  private _stubPath(moduleName: string): string {
+    // Replace dots with hyphens for filesystem safety
+    const safeName = moduleName.replace(/\./g, '-');
+    return path.join(this._stubsDir, `${safeName}.d.ts`);
+  }
+
+  private _isStale(meta: StubMeta, libVersion?: string): boolean {
+    // Age check — use createdAt if present (test compatibility), else generatedAt
+    const timestamp = (meta as unknown as Record<string, number>)['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;
+  }
+
+  private _readnodepyxVersion(): string {
+    try {
+      const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version?: string };
+        return pkg.version ?? '0.0.0';
+      }
+    } catch {
+      // ignore
+    }
+    return '0.0.0';
+  }
+
+  /** djb2 hash — fast, not cryptographic */
+  private _hash(content: string): string {
+    let h = 5381;
+    for (let i = 0; i < content.length; i++) {
+      h = ((h << 5) + h + content.charCodeAt(i)) >>> 0;
+    }
+    return h.toString(16);
+  }
+}
+