@socketsecurity/lib 0.0.0 → 1.0.0

package/dist/paths.js

@@ -0,0 +1,145 @@
+/* Socket Lib - Built with esbuild */
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var paths_exports = {};
+__export(paths_exports, {
+  getSocketAppCacheDir: () => getSocketAppCacheDir,
+  getSocketAppCacheTtlDir: () => getSocketAppCacheTtlDir,
+  getSocketAppDir: () => getSocketAppDir,
+  getSocketCacacheDir: () => getSocketCacacheDir,
+  getSocketCliDir: () => getSocketCliDir,
+  getSocketDlxDir: () => getSocketDlxDir,
+  getSocketHomePath: () => getSocketHomePath,
+  getSocketRegistryDir: () => getSocketRegistryDir,
+  getSocketRegistryGithubCacheDir: () => getSocketRegistryGithubCacheDir,
+  getSocketUserDir: () => getSocketUserDir
+});
+module.exports = __toCommonJS(paths_exports);
+var os = __toESM(require("node:os"));
+var path = __toESM(require("node:path"));
+var import_socket_cacache_dir = require("#env/socket-cacache-dir");
+var import_path = require("./path");
+function getSocketHomePath() {
+  return getSocketUserDir();
+}
+function getSocketUserDir() {
+  return (0, import_path.normalizePath)(
+    path.join(
+      os.homedir(),
+      /*@__INLINE__*/
+      require("./constants/paths").DOT_SOCKET_DIR
+    )
+  );
+}
+function getSocketAppDir(appName) {
+  return (0, import_path.normalizePath)(
+    path.join(
+      getSocketUserDir(),
+      `${/*@__INLINE__*/
+      require("./constants/socket").SOCKET_APP_PREFIX}${appName}`
+    )
+  );
+}
+function getSocketCacacheDir() {
+  if (import_socket_cacache_dir.SOCKET_CACACHE_DIR) {
+    return (0, import_path.normalizePath)(import_socket_cacache_dir.SOCKET_CACACHE_DIR);
+  }
+  return (0, import_path.normalizePath)(
+    path.join(
+      getSocketUserDir(),
+      `${/*@__INLINE__*/
+      require("./constants/socket").SOCKET_APP_PREFIX}cacache`
+    )
+  );
+}
+function getSocketDlxDir() {
+  return (0, import_path.normalizePath)(
+    path.join(
+      getSocketUserDir(),
+      `${/*@__INLINE__*/
+      require("./constants/socket").SOCKET_APP_PREFIX}${/*@__INLINE__*/
+      require("./constants/socket").SOCKET_DLX_APP_NAME}`
+    )
+  );
+}
+function getSocketAppCacheDir(appName) {
+  return (0, import_path.normalizePath)(
+    path.join(
+      getSocketAppDir(appName),
+      /*@__INLINE__*/
+      require("./constants/paths").CACHE_DIR
+    )
+  );
+}
+function getSocketAppCacheTtlDir(appName) {
+  return (0, import_path.normalizePath)(
+    path.join(
+      getSocketAppCacheDir(appName),
+      /*@__INLINE__*/
+      require("./constants/paths").CACHE_TTL_DIR
+    )
+  );
+}
+function getSocketCliDir() {
+  return getSocketAppDir(
+    /*@__INLINE__*/
+    require("./constants/socket").SOCKET_CLI_APP_NAME
+  );
+}
+function getSocketRegistryDir() {
+  return getSocketAppDir(
+    /*@__INLINE__*/
+    require("./constants/socket").SOCKET_REGISTRY_APP_NAME
+  );
+}
+function getSocketRegistryGithubCacheDir() {
+  return (0, import_path.normalizePath)(
+    path.join(
+      getSocketAppCacheTtlDir(
+        /*@__INLINE__*/
+        require("./constants/socket").SOCKET_REGISTRY_APP_NAME
+      ),
+      /*@__INLINE__*/
+      require("./constants/github").CACHE_GITHUB_DIR
+    )
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSocketAppCacheDir,
+  getSocketAppCacheTtlDir,
+  getSocketAppDir,
+  getSocketCacacheDir,
+  getSocketCliDir,
+  getSocketDlxDir,
+  getSocketHomePath,
+  getSocketRegistryDir,
+  getSocketRegistryGithubCacheDir,
+  getSocketUserDir
+});
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/paths.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Path utilities for Socket ecosystem directories.\n * Provides platform-aware path resolution for Socket tools' shared directory structure.\n *\n * Directory Structure:\n * ~/.socket/\n * \u251C\u2500\u2500 _cacache/           # Content-addressable cache (shared)\n * \u251C\u2500\u2500 _dlx/               # DLX tool installations (shared)\n * \u251C\u2500\u2500 _socket/            # Socket CLI app directory\n * \u251C\u2500\u2500 _registry/          # Socket Registry app directory\n * \u2514\u2500\u2500 _sfw/               # Socket Firewall app directory\n */\n\nimport * as os from 'node:os'\nimport * as path from 'node:path'\n\nimport { SOCKET_CACACHE_DIR } from '#env/socket-cacache-dir'\n\nimport { normalizePath } from './path'\n\n/**\n * Get the Socket home directory (~/.socket).\n * Alias for getSocketUserDir() for consistency across Socket projects.\n */\nexport function getSocketHomePath(): string {\n  return getSocketUserDir()\n}\n\n/**\n * Get the Socket user directory (~/.socket).\n */\nexport function getSocketUserDir(): string {\n  return normalizePath(\n    path.join(\n      os.homedir(),\n      /*@__INLINE__*/ require('./constants/paths').DOT_SOCKET_DIR,\n    ),\n  )\n}\n\n/**\n * Get a Socket app directory (~/.socket/_<appName>).\n */\nexport function getSocketAppDir(appName: string): string {\n  return normalizePath(\n    path.join(\n      getSocketUserDir(),\n      `${/*@__INLINE__*/ require('./constants/socket').SOCKET_APP_PREFIX}${appName}`,\n    ),\n  )\n}\n\n/**\n * Get the Socket cacache directory (~/.socket/_cacache).\n * Can be overridden with SOCKET_CACACHE_DIR environment variable for testing.\n */\nexport function getSocketCacacheDir(): string {\n  if (SOCKET_CACACHE_DIR) {\n    return normalizePath(SOCKET_CACACHE_DIR)\n  }\n  return normalizePath(\n    path.join(\n      getSocketUserDir(),\n      `${/*@__INLINE__*/ require('./constants/socket').SOCKET_APP_PREFIX}cacache`,\n    ),\n  )\n}\n\n/**\n * Get the Socket DLX directory (~/.socket/_dlx).\n */\nexport function getSocketDlxDir(): string {\n  return normalizePath(\n    path.join(\n      getSocketUserDir(),\n      `${/*@__INLINE__*/ require('./constants/socket').SOCKET_APP_PREFIX}${/*@__INLINE__*/ require('./constants/socket').SOCKET_DLX_APP_NAME}`,\n    ),\n  )\n}\n\n/**\n * Get a Socket app cache directory (~/.socket/_<appName>/cache).\n */\nexport function getSocketAppCacheDir(appName: string): string {\n  return normalizePath(\n    path.join(\n      getSocketAppDir(appName),\n      /*@__INLINE__*/ require('./constants/paths').CACHE_DIR,\n    ),\n  )\n}\n\n/**\n * Get a Socket app TTL cache directory (~/.socket/_<appName>/cache/ttl).\n */\nexport function getSocketAppCacheTtlDir(appName: string): string {\n  return normalizePath(\n    path.join(\n      getSocketAppCacheDir(appName),\n      /*@__INLINE__*/ require('./constants/paths').CACHE_TTL_DIR,\n    ),\n  )\n}\n\n/**\n * Get the Socket CLI directory (~/.socket/_socket).\n */\nexport function getSocketCliDir(): string {\n  return getSocketAppDir(\n    /*@__INLINE__*/ require('./constants/socket').SOCKET_CLI_APP_NAME,\n  )\n}\n\n/**\n * Get the Socket Registry directory (~/.socket/_registry).\n */\nexport function getSocketRegistryDir(): string {\n  return getSocketAppDir(\n    /*@__INLINE__*/ require('./constants/socket').SOCKET_REGISTRY_APP_NAME,\n  )\n}\n\n/**\n * Get the Socket Registry GitHub cache directory (~/.socket/_registry/cache/ttl/github).\n */\nexport function getSocketRegistryGithubCacheDir(): string {\n  return normalizePath(\n    path.join(\n      getSocketAppCacheTtlDir(\n        /*@__INLINE__*/ require('./constants/socket').SOCKET_REGISTRY_APP_NAME,\n      ),\n      /*@__INLINE__*/ require('./constants/github').CACHE_GITHUB_DIR,\n    ),\n  )\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAaA,SAAoB;AACpB,WAAsB;AAEtB,gCAAmC;AAEnC,kBAA8B;AAMvB,SAAS,oBAA4B;AAC1C,SAAO,iBAAiB;AAC1B;AAKO,SAAS,mBAA2B;AACzC,aAAO;AAAA,IACL,KAAK;AAAA,MACH,GAAG,QAAQ;AAAA;AAAA,MACK,QAAQ,mBAAmB,EAAE;AAAA,IAC/C;AAAA,EACF;AACF;AAKO,SAAS,gBAAgB,SAAyB;AACvD,aAAO;AAAA,IACL,KAAK;AAAA,MACH,iBAAiB;AAAA,MACjB;AAAA,MAAmB,QAAQ,oBAAoB,EAAE,iBAAiB,GAAG,OAAO;AAAA,IAC9E;AAAA,EACF;AACF;AAMO,SAAS,sBAA8B;AAC5C,MAAI,8CAAoB;AACtB,eAAO,2BAAc,4CAAkB;AAAA,EACzC;AACA,aAAO;AAAA,IACL,KAAK;AAAA,MACH,iBAAiB;AAAA,MACjB;AAAA,MAAmB,QAAQ,oBAAoB,EAAE,iBAAiB;AAAA,IACpE;AAAA,EACF;AACF;AAKO,SAAS,kBAA0B;AACxC,aAAO;AAAA,IACL,KAAK;AAAA,MACH,iBAAiB;AAAA,MACjB;AAAA,MAAmB,QAAQ,oBAAoB,EAAE,iBAAiB;AAAA,MAAmB,QAAQ,oBAAoB,EAAE,mBAAmB;AAAA,IACxI;AAAA,EACF;AACF;AAKO,SAAS,qBAAqB,SAAyB;AAC5D,aAAO;AAAA,IACL,KAAK;AAAA,MACH,gBAAgB,OAAO;AAAA;AAAA,MACP,QAAQ,mBAAmB,EAAE;AAAA,IAC/C;AAAA,EACF;AACF;AAKO,SAAS,wBAAwB,SAAyB;AAC/D,aAAO;AAAA,IACL,KAAK;AAAA,MACH,qBAAqB,OAAO;AAAA;AAAA,MACZ,QAAQ,mBAAmB,EAAE;AAAA,IAC/C;AAAA,EACF;AACF;AAKO,SAAS,kBAA0B;AACxC,SAAO;AAAA;AAAA,IACW,QAAQ,oBAAoB,EAAE;AAAA,EAChD;AACF;AAKO,SAAS,uBAA+B;AAC7C,SAAO;AAAA;AAAA,IACW,QAAQ,oBAAoB,EAAE;AAAA,EAChD;AACF;AAKO,SAAS,kCAA0C;AACxD,aAAO;AAAA,IACL,KAAK;AAAA,MACH;AAAA;AAAA,QACkB,QAAQ,oBAAoB,EAAE;AAAA,MAChD;AAAA;AAAA,MACgB,QAAQ,oBAAoB,EAAE;AAAA,IAChD;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/performance.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Performance metrics collected during execution.
+ */
+type PerformanceMetrics = {
+    operation: string;
+    duration: number;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Start a performance timer for an operation.
+ * Returns a stop function that records the duration.
+ *
+ * @param operation - Name of the operation being timed
+ * @param metadata - Optional metadata to attach to the metric
+ * @returns Stop function that completes the timing
+ *
+ * @example
+ * import { perfTimer } from '@socketsecurity/registry/lib/performance'
+ *
+ * const stop = perfTimer('api-call')
+ * await fetchData()
+ * stop({ endpoint: '/npm/lodash/score' })
+ */
+export declare function perfTimer(operation: string, metadata?: Record<string, unknown>): (additionalMetadata?: Record<string, unknown>) => void;
+/**
+ * Measure execution time of an async function.
+ *
+ * @param operation - Name of the operation
+ * @param fn - Async function to measure
+ * @param metadata - Optional metadata
+ * @returns Result of the function and duration
+ *
+ * @example
+ * import { measure } from '@socketsecurity/registry/lib/performance'
+ *
+ * const { result, duration } = await measure('fetch-packages', async () => {
+ *   return await fetchPackages()
+ * })
+ * console.log(`Fetched packages in ${duration}ms`)
+ */
+export declare function measure<T>(operation: string, fn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<{
+    result: T;
+    duration: number;
+}>;
+/**
+ * Measure synchronous function execution time.
+ *
+ * @param operation - Name of the operation
+ * @param fn - Synchronous function to measure
+ * @param metadata - Optional metadata
+ * @returns Result of the function and duration
+ *
+ * @example
+ * import { measureSync } from '@socketsecurity/registry/lib/performance'
+ *
+ * const { result, duration } = measureSync('parse-json', () => {
+ *   return JSON.parse(data)
+ * })
+ */
+export declare function measureSync<T>(operation: string, fn: () => T, metadata?: Record<string, unknown>): {
+    result: T;
+    duration: number;
+};
+/**
+ * Get all collected performance metrics.
+ * Only available when DEBUG=perf is enabled.
+ *
+ * @returns Array of performance metrics
+ *
+ * @example
+ * import { getPerformanceMetrics } from '@socketsecurity/registry/lib/performance'
+ *
+ * const metrics = getPerformanceMetrics()
+ * console.log(metrics)
+ */
+export declare function getPerformanceMetrics(): PerformanceMetrics[];
+/**
+ * Clear all collected performance metrics.
+ *
+ * @example
+ * import { clearPerformanceMetrics } from '@socketsecurity/registry/lib/performance'
+ *
+ * clearPerformanceMetrics()
+ */
+export declare function clearPerformanceMetrics(): void;
+/**
+ * Get performance summary statistics.
+ *
+ * @returns Summary of metrics grouped by operation
+ *
+ * @example
+ * import { getPerformanceSummary } from '@socketsecurity/registry/lib/performance'
+ *
+ * const summary = getPerformanceSummary()
+ * console.log(summary)
+ * // {
+ * //   'api-call': { count: 5, total: 1234, avg: 246.8, min: 100, max: 500 },
+ * //   'file-read': { count: 10, total: 50, avg: 5, min: 2, max: 15 }
+ * // }
+ */
+export declare function getPerformanceSummary(): Record<string, {
+    count: number;
+    total: number;
+    avg: number;
+    min: number;
+    max: number;
+}>;
+/**
+ * Print performance summary to console.
+ * Only prints when DEBUG=perf is enabled.
+ *
+ * @example
+ * import { printPerformanceSummary } from '@socketsecurity/registry/lib/performance'
+ *
+ * printPerformanceSummary()
+ * // Performance Summary:
+ * // api-call: 5 calls, avg 246.8ms (min 100ms, max 500ms, total 1234ms)
+ * // file-read: 10 calls, avg 5ms (min 2ms, max 15ms, total 50ms)
+ */
+export declare function printPerformanceSummary(): void;
+/**
+ * Mark a checkpoint in performance tracking.
+ * Useful for tracking progress through complex operations.
+ *
+ * @param checkpoint - Name of the checkpoint
+ * @param metadata - Optional metadata
+ *
+ * @example
+ * import { perfCheckpoint } from '@socketsecurity/registry/lib/performance'
+ *
+ * perfCheckpoint('start-scan')
+ * // ... do work ...
+ * perfCheckpoint('fetch-packages', { count: 50 })
+ * // ... do work ...
+ * perfCheckpoint('analyze-issues', { issueCount: 10 })
+ * perfCheckpoint('end-scan')
+ */
+export declare function perfCheckpoint(checkpoint: string, metadata?: Record<string, unknown>): void;
+/**
+ * Track memory usage at a specific point.
+ * Only available when DEBUG=perf is enabled.
+ *
+ * @param label - Label for this memory snapshot
+ * @returns Memory usage in MB
+ *
+ * @example
+ * import { trackMemory } from '@socketsecurity/registry/lib/performance'
+ *
+ * const memBefore = trackMemory('before-operation')
+ * await heavyOperation()
+ * const memAfter = trackMemory('after-operation')
+ * console.log(`Memory increased by ${memAfter - memBefore}MB`)
+ */
+export declare function trackMemory(label: string): number;
+/**
+ * Create a performance report for the current execution.
+ * Only available when DEBUG=perf is enabled.
+ *
+ * @returns Formatted performance report
+ *
+ * @example
+ * import { generatePerformanceReport } from '@socketsecurity/registry/lib/performance'
+ *
+ * console.log(generatePerformanceReport())
+ * // ╔═══════════════════════════════════════════════╗
+ * // ║         Performance Report                    ║
+ * // ╚═══════════════════════════════════════════════╝
+ * //
+ * // api-call:
+ * //   Calls: 5
+ * //   Avg:   246.8ms
+ * //   Min:   100ms
+ * //   Max:   500ms
+ * //   Total: 1234ms
+ */
+export declare function generatePerformanceReport(): string;
+export {};

package/dist/performance.js

@@ -0,0 +1,219 @@
+/* Socket Lib - Built with esbuild */
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var performance_exports = {};
+__export(performance_exports, {
+  clearPerformanceMetrics: () => clearPerformanceMetrics,
+  generatePerformanceReport: () => generatePerformanceReport,
+  getPerformanceMetrics: () => getPerformanceMetrics,
+  getPerformanceSummary: () => getPerformanceSummary,
+  measure: () => measure,
+  measureSync: () => measureSync,
+  perfCheckpoint: () => perfCheckpoint,
+  perfTimer: () => perfTimer,
+  printPerformanceSummary: () => printPerformanceSummary,
+  trackMemory: () => trackMemory
+});
+module.exports = __toCommonJS(performance_exports);
+var import_debug = require("./debug");
+const performanceMetrics = [];
+function isPerfEnabled() {
+  return process.env["DEBUG"]?.includes("perf") || false;
+}
+function perfTimer(operation, metadata) {
+  if (!isPerfEnabled()) {
+    return () => {
+    };
+  }
+  const start = performance.now();
+  (0, import_debug.debugLog)(`[perf] [START] ${operation}`);
+  return (additionalMetadata) => {
+    const duration = performance.now() - start;
+    const metric = {
+      operation,
+      // Round to 2 decimals
+      duration: Math.round(duration * 100) / 100,
+      timestamp: Date.now(),
+      metadata: { ...metadata, ...additionalMetadata }
+    };
+    performanceMetrics.push(metric);
+    (0, import_debug.debugLog)(`[perf] [END] ${operation} - ${metric.duration}ms`);
+  };
+}
+async function measure(operation, fn, metadata) {
+  const stop = perfTimer(operation, metadata);
+  try {
+    const result = await fn();
+    stop({ success: true });
+    const metric = performanceMetrics[performanceMetrics.length - 1];
+    return { result, duration: metric?.duration || 0 };
+  } catch (e) {
+    stop({
+      success: false,
+      error: e instanceof Error ? e.message : "Unknown"
+    });
+    throw e;
+  }
+}
+function measureSync(operation, fn, metadata) {
+  const stop = perfTimer(operation, metadata);
+  try {
+    const result = fn();
+    stop({ success: true });
+    const metric = performanceMetrics[performanceMetrics.length - 1];
+    return { result, duration: metric?.duration || 0 };
+  } catch (e) {
+    stop({
+      success: false,
+      error: e instanceof Error ? e.message : "Unknown"
+    });
+    throw e;
+  }
+}
+function getPerformanceMetrics() {
+  return [...performanceMetrics];
+}
+function clearPerformanceMetrics() {
+  performanceMetrics.length = 0;
+  (0, import_debug.debugLog)("[perf] Cleared performance metrics");
+}
+function getPerformanceSummary() {
+  const summary = /* @__PURE__ */ Object.create(null);
+  for (const metric of performanceMetrics) {
+    const { duration, operation } = metric;
+    if (!summary[operation]) {
+      summary[operation] = {
+        count: 0,
+        total: 0,
+        min: Number.POSITIVE_INFINITY,
+        max: Number.NEGATIVE_INFINITY
+      };
+    }
+    const stats = summary[operation];
+    stats.count++;
+    stats.total += duration;
+    stats.min = Math.min(stats.min, duration);
+    stats.max = Math.max(stats.max, duration);
+  }
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const { 0: operation, 1: stats } of Object.entries(summary)) {
+    result[operation] = {
+      count: stats.count,
+      total: Math.round(stats.total * 100) / 100,
+      avg: Math.round(stats.total / stats.count * 100) / 100,
+      min: Math.round(stats.min * 100) / 100,
+      max: Math.round(stats.max * 100) / 100
+    };
+  }
+  return result;
+}
+function printPerformanceSummary() {
+  if (!isPerfEnabled() || performanceMetrics.length === 0) {
+    return;
+  }
+  const summary = getPerformanceSummary();
+  const operations = Object.keys(summary).sort();
+  (0, import_debug.debugLog)("[perf]\n=== Performance Summary ===");
+  for (const operation of operations) {
+    const stats = summary[operation];
+    (0, import_debug.debugLog)(
+      `[perf] ${operation}: ${stats.count} calls, avg ${stats.avg}ms (min ${stats.min}ms, max ${stats.max}ms, total ${stats.total}ms)`
+    );
+  }
+  (0, import_debug.debugLog)("[perf] =========================\n");
+}
+function perfCheckpoint(checkpoint, metadata) {
+  if (!isPerfEnabled()) {
+    return;
+  }
+  const metric = {
+    operation: `checkpoint:${checkpoint}`,
+    duration: 0,
+    timestamp: Date.now(),
+    ...metadata ? { metadata } : {}
+  };
+  performanceMetrics.push(metric);
+  (0, import_debug.debugLog)(`[perf] [CHECKPOINT] ${checkpoint}`);
+}
+function trackMemory(label) {
+  if (!isPerfEnabled()) {
+    return 0;
+  }
+  const usage = process.memoryUsage();
+  const heapUsedMB = Math.round(usage.heapUsed / 1024 / 1024 * 100) / 100;
+  (0, import_debug.debugLog)(`[perf] [MEMORY] ${label}: ${heapUsedMB}MB heap used`);
+  const metric = {
+    operation: `checkpoint:memory:${label}`,
+    duration: 0,
+    timestamp: Date.now(),
+    metadata: {
+      heapUsed: heapUsedMB,
+      heapTotal: Math.round(usage.heapTotal / 1024 / 1024 * 100) / 100,
+      external: Math.round(usage.external / 1024 / 1024 * 100) / 100
+    }
+  };
+  performanceMetrics.push(metric);
+  return heapUsedMB;
+}
+function generatePerformanceReport() {
+  if (!isPerfEnabled() || performanceMetrics.length === 0) {
+    return "(no performance data collected - enable with DEBUG=perf)";
+  }
+  const summary = getPerformanceSummary();
+  const operations = Object.keys(summary).sort();
+  let report = "\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n";
+  report += "\u2551         Performance Report                    \u2551\n";
+  report += "\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\n\n";
+  for (const operation of operations) {
+    const stats = summary[operation];
+    report += `${operation}:
+`;
+    report += `  Calls: ${stats.count}
+`;
+    report += `  Avg:   ${stats.avg}ms
+`;
+    report += `  Min:   ${stats.min}ms
+`;
+    report += `  Max:   ${stats.max}ms
+`;
+    report += `  Total: ${stats.total}ms
+
+`;
+  }
+  const totalDuration = Object.values(summary).reduce(
+    (sum, s) => sum + s.total,
+    0
+  );
+  report += `Total measured time: ${Math.round(totalDuration * 100) / 100}ms
+`;
+  return report;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearPerformanceMetrics,
+  generatePerformanceReport,
+  getPerformanceMetrics,
+  getPerformanceSummary,
+  measure,
+  measureSync,
+  perfCheckpoint,
+  perfTimer,
+  printPerformanceSummary,
+  trackMemory
+});
+//# sourceMappingURL=performance.js.map

package/dist/performance.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/performance.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Performance monitoring utilities for profiling and optimization.\n * Provides timing, profiling, and performance metric collection for identifying bottlenecks.\n */\n\nimport { debugLog } from './debug'\n\n/**\n * Performance metrics collected during execution.\n */\ntype PerformanceMetrics = {\n  operation: string\n  duration: number\n  timestamp: number\n  metadata?: Record<string, unknown>\n}\n\n/**\n * Global metrics collection (only in debug mode).\n */\nconst performanceMetrics: PerformanceMetrics[] = []\n\n/**\n * Check if performance tracking is enabled.\n */\nfunction isPerfEnabled(): boolean {\n  return process.env['DEBUG']?.includes('perf') || false\n}\n\n/**\n * Start a performance timer for an operation.\n * Returns a stop function that records the duration.\n *\n * @param operation - Name of the operation being timed\n * @param metadata - Optional metadata to attach to the metric\n * @returns Stop function that completes the timing\n *\n * @example\n * import { perfTimer } from '@socketsecurity/registry/lib/performance'\n *\n * const stop = perfTimer('api-call')\n * await fetchData()\n * stop({ endpoint: '/npm/lodash/score' })\n */\nexport function perfTimer(\n  operation: string,\n  metadata?: Record<string, unknown>,\n): (additionalMetadata?: Record<string, unknown>) => void {\n  if (!isPerfEnabled()) {\n    // No-op if perf tracking disabled\n    return () => {}\n  }\n\n  const start = performance.now()\n  debugLog(`[perf] [START] ${operation}`)\n\n  return (additionalMetadata?: Record<string, unknown>) => {\n    const duration = performance.now() - start\n    const metric: PerformanceMetrics = {\n      operation,\n      // Round to 2 decimals\n      duration: Math.round(duration * 100) / 100,\n      timestamp: Date.now(),\n      metadata: { ...metadata, ...additionalMetadata },\n    }\n\n    performanceMetrics.push(metric)\n    debugLog(`[perf] [END] ${operation} - ${metric.duration}ms`)\n  }\n}\n\n/**\n * Measure execution time of an async function.\n *\n * @param operation - Name of the operation\n * @param fn - Async function to measure\n * @param metadata - Optional metadata\n * @returns Result of the function and duration\n *\n * @example\n * import { measure } from '@socketsecurity/registry/lib/performance'\n *\n * const { result, duration } = await measure('fetch-packages', async () => {\n *   return await fetchPackages()\n * })\n * console.log(`Fetched packages in ${duration}ms`)\n */\nexport async function measure<T>(\n  operation: string,\n  fn: () => Promise<T>,\n  metadata?: Record<string, unknown>,\n): Promise<{ result: T; duration: number }> {\n  const stop = perfTimer(operation, metadata)\n\n  try {\n    const result = await fn()\n    stop({ success: true })\n\n    const metric = performanceMetrics[performanceMetrics.length - 1]\n    return { result, duration: metric?.duration || 0 }\n  } catch (e) {\n    stop({\n      success: false,\n      error: e instanceof Error ? e.message : 'Unknown',\n    })\n    throw e\n  }\n}\n\n/**\n * Measure synchronous function execution time.\n *\n * @param operation - Name of the operation\n * @param fn - Synchronous function to measure\n * @param metadata - Optional metadata\n * @returns Result of the function and duration\n *\n * @example\n * import { measureSync } from '@socketsecurity/registry/lib/performance'\n *\n * const { result, duration } = measureSync('parse-json', () => {\n *   return JSON.parse(data)\n * })\n */\nexport function measureSync<T>(\n  operation: string,\n  fn: () => T,\n  metadata?: Record<string, unknown>,\n): { result: T; duration: number } {\n  const stop = perfTimer(operation, metadata)\n\n  try {\n    const result = fn()\n    stop({ success: true })\n\n    const metric = performanceMetrics[performanceMetrics.length - 1]\n    return { result, duration: metric?.duration || 0 }\n  } catch (e) {\n    stop({\n      success: false,\n      error: e instanceof Error ? e.message : 'Unknown',\n    })\n    throw e\n  }\n}\n\n/**\n * Get all collected performance metrics.\n * Only available when DEBUG=perf is enabled.\n *\n * @returns Array of performance metrics\n *\n * @example\n * import { getPerformanceMetrics } from '@socketsecurity/registry/lib/performance'\n *\n * const metrics = getPerformanceMetrics()\n * console.log(metrics)\n */\nexport function getPerformanceMetrics(): PerformanceMetrics[] {\n  return [...performanceMetrics]\n}\n\n/**\n * Clear all collected performance metrics.\n *\n * @example\n * import { clearPerformanceMetrics } from '@socketsecurity/registry/lib/performance'\n *\n * clearPerformanceMetrics()\n */\nexport function clearPerformanceMetrics(): void {\n  performanceMetrics.length = 0\n  debugLog('[perf] Cleared performance metrics')\n}\n\n/**\n * Get performance summary statistics.\n *\n * @returns Summary of metrics grouped by operation\n *\n * @example\n * import { getPerformanceSummary } from '@socketsecurity/registry/lib/performance'\n *\n * const summary = getPerformanceSummary()\n * console.log(summary)\n * // {\n * //   'api-call': { count: 5, total: 1234, avg: 246.8, min: 100, max: 500 },\n * //   'file-read': { count: 10, total: 50, avg: 5, min: 2, max: 15 }\n * // }\n */\nexport function getPerformanceSummary(): Record<\n  string,\n  {\n    count: number\n    total: number\n    avg: number\n    min: number\n    max: number\n  }\n> {\n  const summary: Record<\n    string,\n    { count: number; total: number; min: number; max: number }\n  > = Object.create(null)\n\n  for (const metric of performanceMetrics) {\n    const { duration, operation } = metric\n\n    if (!summary[operation]) {\n      summary[operation] = {\n        count: 0,\n        total: 0,\n        min: Number.POSITIVE_INFINITY,\n        max: Number.NEGATIVE_INFINITY,\n      }\n    }\n\n    const stats = summary[operation] as {\n      count: number\n      total: number\n      min: number\n      max: number\n    }\n    stats.count++\n    stats.total += duration\n    stats.min = Math.min(stats.min, duration)\n    stats.max = Math.max(stats.max, duration)\n  }\n\n  // Calculate averages and return with proper typing\n  const result: Record<\n    string,\n    { count: number; total: number; avg: number; min: number; max: number }\n  > = Object.create(null)\n\n  for (const { 0: operation, 1: stats } of Object.entries(summary)) {\n    result[operation] = {\n      count: stats.count,\n      total: Math.round(stats.total * 100) / 100,\n      avg: Math.round((stats.total / stats.count) * 100) / 100,\n      min: Math.round(stats.min * 100) / 100,\n      max: Math.round(stats.max * 100) / 100,\n    }\n  }\n\n  return result\n}\n\n/**\n * Print performance summary to console.\n * Only prints when DEBUG=perf is enabled.\n *\n * @example\n * import { printPerformanceSummary } from '@socketsecurity/registry/lib/performance'\n *\n * printPerformanceSummary()\n * // Performance Summary:\n * // api-call: 5 calls, avg 246.8ms (min 100ms, max 500ms, total 1234ms)\n * // file-read: 10 calls, avg 5ms (min 2ms, max 15ms, total 50ms)\n */\nexport function printPerformanceSummary(): void {\n  if (!isPerfEnabled() || performanceMetrics.length === 0) {\n    return\n  }\n\n  const summary = getPerformanceSummary()\n  const operations = Object.keys(summary).sort()\n\n  debugLog('[perf]\\n=== Performance Summary ===')\n\n  for (const operation of operations) {\n    const stats = summary[operation] as {\n      count: number\n      total: number\n      avg: number\n      min: number\n      max: number\n    }\n    debugLog(\n      `[perf] ${operation}: ${stats.count} calls, avg ${stats.avg}ms (min ${stats.min}ms, max ${stats.max}ms, total ${stats.total}ms)`,\n    )\n  }\n\n  debugLog('[perf] =========================\\n')\n}\n\n/**\n * Mark a checkpoint in performance tracking.\n * Useful for tracking progress through complex operations.\n *\n * @param checkpoint - Name of the checkpoint\n * @param metadata - Optional metadata\n *\n * @example\n * import { perfCheckpoint } from '@socketsecurity/registry/lib/performance'\n *\n * perfCheckpoint('start-scan')\n * // ... do work ...\n * perfCheckpoint('fetch-packages', { count: 50 })\n * // ... do work ...\n * perfCheckpoint('analyze-issues', { issueCount: 10 })\n * perfCheckpoint('end-scan')\n */\nexport function perfCheckpoint(\n  checkpoint: string,\n  metadata?: Record<string, unknown>,\n): void {\n  if (!isPerfEnabled()) {\n    return\n  }\n\n  const metric: PerformanceMetrics = {\n    operation: `checkpoint:${checkpoint}`,\n    duration: 0,\n    timestamp: Date.now(),\n    ...(metadata ? { metadata } : {}),\n  }\n\n  performanceMetrics.push(metric)\n  debugLog(`[perf] [CHECKPOINT] ${checkpoint}`)\n}\n\n/**\n * Track memory usage at a specific point.\n * Only available when DEBUG=perf is enabled.\n *\n * @param label - Label for this memory snapshot\n * @returns Memory usage in MB\n *\n * @example\n * import { trackMemory } from '@socketsecurity/registry/lib/performance'\n *\n * const memBefore = trackMemory('before-operation')\n * await heavyOperation()\n * const memAfter = trackMemory('after-operation')\n * console.log(`Memory increased by ${memAfter - memBefore}MB`)\n */\nexport function trackMemory(label: string): number {\n  if (!isPerfEnabled()) {\n    return 0\n  }\n\n  const usage = process.memoryUsage()\n  const heapUsedMB = Math.round((usage.heapUsed / 1024 / 1024) * 100) / 100\n\n  debugLog(`[perf] [MEMORY] ${label}: ${heapUsedMB}MB heap used`)\n\n  const metric: PerformanceMetrics = {\n    operation: `checkpoint:memory:${label}`,\n    duration: 0,\n    timestamp: Date.now(),\n    metadata: {\n      heapUsed: heapUsedMB,\n      heapTotal: Math.round((usage.heapTotal / 1024 / 1024) * 100) / 100,\n      external: Math.round((usage.external / 1024 / 1024) * 100) / 100,\n    },\n  }\n\n  performanceMetrics.push(metric)\n\n  return heapUsedMB\n}\n\n/**\n * Create a performance report for the current execution.\n * Only available when DEBUG=perf is enabled.\n *\n * @returns Formatted performance report\n *\n * @example\n * import { generatePerformanceReport } from '@socketsecurity/registry/lib/performance'\n *\n * console.log(generatePerformanceReport())\n * // \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n * // \u2551         Performance Report                    \u2551\n * // \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\n * //\n * // api-call:\n * //   Calls: 5\n * //   Avg:   246.8ms\n * //   Min:   100ms\n * //   Max:   500ms\n * //   Total: 1234ms\n */\nexport function generatePerformanceReport(): string {\n  if (!isPerfEnabled() || performanceMetrics.length === 0) {\n    return '(no performance data collected - enable with DEBUG=perf)'\n  }\n\n  const summary = getPerformanceSummary()\n  const operations = Object.keys(summary).sort()\n\n  let report = '\\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\\n'\n  report += '\u2551         Performance Report                    \u2551\\n'\n  report += '\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\\n\\n'\n\n  for (const operation of operations) {\n    const stats = summary[operation] as {\n      count: number\n      total: number\n      avg: number\n      min: number\n      max: number\n    }\n    report += `${operation}:\\n`\n    report += `  Calls: ${stats.count}\\n`\n    report += `  Avg:   ${stats.avg}ms\\n`\n    report += `  Min:   ${stats.min}ms\\n`\n    report += `  Max:   ${stats.max}ms\\n`\n    report += `  Total: ${stats.total}ms\\n\\n`\n  }\n\n  const totalDuration = Object.values(summary).reduce(\n    (sum, s) => sum + s.total,\n    0,\n  )\n  report += `Total measured time: ${Math.round(totalDuration * 100) / 100}ms\\n`\n\n  return report\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/promise-queue.d.ts

@@ -0,0 +1,35 @@
+export declare class PromiseQueue {
+    private queue;
+    private running;
+    private readonly maxConcurrency;
+    private readonly maxQueueLength;
+    /**
+     * Creates a new PromiseQueue
+     * @param maxConcurrency - Maximum number of promises that can run concurrently
+     * @param maxQueueLength - Maximum queue size (older tasks are dropped if exceeded)
+     */
+    constructor(maxConcurrency: number, maxQueueLength?: number | undefined);
+    /**
+     * Add a task to the queue
+     * @param fn - Async function to execute
+     * @returns Promise that resolves with the function's result
+     */
+    add<T>(fn: () => Promise<T>): Promise<T>;
+    private runNext;
+    /**
+     * Wait for all queued and running tasks to complete
+     */
+    onIdle(): Promise<void>;
+    /**
+     * Get the number of tasks currently running
+     */
+    get activeCount(): number;
+    /**
+     * Get the number of tasks waiting in the queue
+     */
+    get pendingCount(): number;
+    /**
+     * Clear all pending tasks from the queue (does not affect running tasks)
+     */
+    clear(): void;
+}