@preship/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+type ProjectType = 'npm' | 'yarn' | 'pnpm';
+interface DetectedProject {
+    type: ProjectType;
+    path: string;
+    lockFile: string;
+    framework?: string;
+}
+interface Dependency {
+    name: string;
+    version: string;
+    license: string;
+    licenseSource: LicenseSource;
+    path?: string;
+    isDirect: boolean;
+    isDevDependency: boolean;
+}
+type LicenseSource = 'package-json-license-field' | 'license-file' | 'package-json-licenses-field' | 'npm-registry' | 'github-api' | 'cache' | 'unknown';
+interface ParsedDependency {
+    name: string;
+    version: string;
+    isDirect: boolean;
+    isDevDependency: boolean;
+}
+type PolicyVerdict = 'allowed' | 'warned' | 'rejected' | 'unknown';
+interface PolicyResult {
+    dependency: Dependency;
+    verdict: PolicyVerdict;
+    reason: string;
+}
+interface ScanResult {
+    projectPath: string;
+    projectType: ProjectType;
+    framework?: string;
+    timestamp: string;
+    totalPackages: number;
+    allowed: PolicyResult[];
+    warned: PolicyResult[];
+    rejected: PolicyResult[];
+    unknown: PolicyResult[];
+    passed: boolean;
+    scanDurationMs: number;
+}
+type ResolverMode = 'auto' | 'online' | 'local';
+interface PreshipConfig {
+    policy?: string;
+    reject?: string[];
+    warn?: string[];
+    allow?: string[];
+    flagUnknown?: boolean;
+    scanDevDependencies?: boolean;
+    exceptions?: ExceptionEntry[];
+    output?: 'table' | 'json' | 'csv';
+    mode?: ResolverMode;
+    networkTimeout?: number;
+    networkConcurrency?: number;
+    cache?: boolean;
+    cacheTTL?: number;
+    scanTimeout?: number;
+}
+interface ExceptionEntry {
+    package: string;
+    reason: string;
+    approvedBy?: string;
+    date?: string;
+}
+interface PolicyTemplate {
+    name: string;
+    description: string;
+    reject: string[];
+    warn: string[];
+    allow: string[];
+    flagUnknown: boolean;
+    scanDevDependencies: boolean;
+}
+
+declare function loadConfig(projectPath: string): PreshipConfig;
+
+declare function detectProjects(rootPath: string): DetectedProject[];
+
+declare function parseNpmLockfile(lockfilePath: string, packageJsonPath: string): ParsedDependency[];
+
+declare function parseYarnLockfile(lockfilePath: string, packageJsonPath: string): ParsedDependency[];
+
+declare function parsePnpmLockfile(lockfilePath: string, packageJsonPath: string): ParsedDependency[];
+
+/**
+ * Encrypted Project-Level License Cache
+ *
+ * Caches resolved license data in `.preship-cache.json` (encrypted with AES-256-CBC).
+ * Encryption key is stored in `.preship-key` (generated once, gitignored).
+ *
+ * Cache key: "packageName@version" — license doesn't change for a given version.
+ * UNKNOWN results are NOT cached (failures may resolve on next scan).
+ */
+interface CacheEntry {
+    license: string;
+    licenseSource: string;
+    cachedAt: number;
+}
+interface CacheFile {
+    version: 1;
+    entries: Record<string, CacheEntry>;
+}
+/**
+ * Load or generate the encryption key.
+ * Key is a 32-byte random value stored as hex in `.preship-key`.
+ */
+declare function getOrCreateKey(projectPath: string): Buffer;
+/**
+ * Build cache key from package name and version.
+ */
+declare function cacheKey(packageName: string, version: string): string;
+/**
+ * Create an empty cache file structure.
+ */
+declare function createEmptyCache(): CacheFile;
+/**
+ * Load cache from disk, decrypt, and parse.
+ * Returns empty cache if file doesn't exist, is corrupt, or key is wrong.
+ */
+declare function loadCache(cacheFilePath: string, key: Buffer): CacheFile;
+/**
+ * Save cache to disk: serialize → encrypt → atomic write (write .tmp then rename).
+ */
+declare function saveCache(cacheFilePath: string, cache: CacheFile, key: Buffer): void;
+/**
+ * Look up a single entry in cache.
+ * Returns null if not found or expired (past TTL).
+ *
+ * @param ttlSeconds - Cache TTL in seconds
+ */
+declare function getCacheEntry(cache: CacheFile, packageName: string, version: string, ttlSeconds: number): CacheEntry | null;
+/**
+ * Set a single entry in cache (in-memory).
+ * Call saveCache() after scan completes to persist.
+ */
+declare function setCacheEntry(cache: CacheFile, packageName: string, version: string, license: string, licenseSource: string): void;
+
+/**
+ * Adaptive Rate Limiter
+ *
+ * Reads rate-limit headers from API responses and slows down
+ * only when approaching limits. Shared across all concurrent
+ * workers in a single scan run.
+ *
+ * Tracks separate state for GitHub API and npm registry.
+ */
+interface RateLimitState {
+    /** Remaining requests before limit (from X-RateLimit-Remaining) */
+    remaining: number | null;
+    /** Total request limit (from X-RateLimit-Limit) */
+    limit: number | null;
+    /** Epoch seconds when limit resets (from X-RateLimit-Reset) */
+    resetAt: number | null;
+    /** Delay in ms from Retry-After header */
+    retryAfterMs: number | null;
+    /** Hard-blocked (403 with 0 remaining) */
+    blocked: boolean;
+}
+interface RateLimiterConfig {
+    /** Threshold ratio at which to start slowing down (default: 0.2 = 20% remaining) */
+    slowdownThreshold: number;
+    /** Maximum delay in ms when approaching limit (default: 2000) */
+    maxDelay: number;
+}
+declare class AdaptiveRateLimiter {
+    private githubState;
+    private npmState;
+    private config;
+    constructor(config?: Partial<RateLimiterConfig>);
+    /**
+     * Update rate-limit state from response headers.
+     * Call after every fetch to either source.
+     *
+     * Reads: X-RateLimit-Remaining, X-RateLimit-Limit, X-RateLimit-Reset, Retry-After
+     */
+    updateFromResponse(source: 'github' | 'npm', response: Response): void;
+    /**
+     * Wait if necessary before making the next request.
+     *
+     * Returns true if OK to proceed, false if the source is hard-blocked.
+     *
+     * Delay logic:
+     * 1. If blocked → return false
+     * 2. If Retry-After is set → wait that exact duration
+     * 3. If remaining/limit < threshold → proportional delay
+     * 4. Otherwise → no delay
+     */
+    waitIfNeeded(source: 'github' | 'npm'): Promise<boolean>;
+    /**
+     * Check if a source is currently hard-blocked.
+     */
+    isBlocked(source: 'github' | 'npm'): boolean;
+    /**
+     * Get the current state for a source (for testing/inspection).
+     */
+    getState(source: 'github' | 'npm'): Readonly<RateLimitState>;
+    /**
+     * Reset all rate-limit state. Call at start of each scan run.
+     */
+    reset(): void;
+    private delay;
+}
+
+/**
+ * Scan Timeout Controller
+ *
+ * Provides a top-level abort mechanism for the entire scan.
+ * When the scan timeout fires, all in-flight and future network requests
+ * are aborted, and the resolver falls back to local resolution (auto mode)
+ * or UNKNOWN (online mode).
+ */
+interface ScanTimeoutController {
+    /** The top-level AbortSignal — aborted when scan timeout fires */
+    signal: AbortSignal;
+    /** Check if the scan has timed out */
+    isTimedOut(): boolean;
+    /**
+     * Create a child AbortController for a single network request.
+     * The child aborts if either:
+     *   - The per-request timeout fires, OR
+     *   - The scan-level timeout fires
+     *
+     * Returns { controller, cleanup }.
+     * ALWAYS call cleanup() after the request completes to prevent memory leaks.
+     */
+    createRequestController(perRequestTimeout: number): {
+        controller: AbortController;
+        cleanup: () => void;
+    };
+    /** Cancel the scan timeout timer. Call when scan completes normally. */
+    dispose(): void;
+}
+/**
+ * Create a scan timeout controller.
+ *
+ * @param timeout - Total scan timeout in ms. 0 or undefined = no timeout (never aborts).
+ */
+declare function createScanTimeoutController(timeout?: number): ScanTimeoutController;
+
+export { AdaptiveRateLimiter, type CacheEntry, type CacheFile, type Dependency, type DetectedProject, type ExceptionEntry, type LicenseSource, type ParsedDependency, type PolicyResult, type PolicyTemplate, type PolicyVerdict, type PreshipConfig, type ProjectType, type ResolverMode, type ScanResult, type ScanTimeoutController, cacheKey, createEmptyCache, createScanTimeoutController, detectProjects, getCacheEntry, getOrCreateKey, loadCache, loadConfig, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile, saveCache, setCacheEntry };

package/dist/index.js

@@ -0,0 +1,912 @@
+"use strict";
+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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AdaptiveRateLimiter: () => AdaptiveRateLimiter,
+  cacheKey: () => cacheKey,
+  createEmptyCache: () => createEmptyCache,
+  createScanTimeoutController: () => createScanTimeoutController,
+  detectProjects: () => detectProjects,
+  getCacheEntry: () => getCacheEntry,
+  getOrCreateKey: () => getOrCreateKey,
+  loadCache: () => loadCache,
+  loadConfig: () => loadConfig,
+  parseNpmLockfile: () => parseNpmLockfile,
+  parsePnpmLockfile: () => parsePnpmLockfile,
+  parseYarnLockfile: () => parseYarnLockfile,
+  saveCache: () => saveCache,
+  setCacheEntry: () => setCacheEntry
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/config.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var yaml = __toESM(require("js-yaml"));
+var CONFIG_FILENAMES = [
+  "preship-config.yml",
+  "preship-config.yaml",
+  "preship-config.json"
+];
+var VALID_POLICIES = ["commercial-safe", "strict", "permissive-only"];
+var VALID_OUTPUTS = ["table", "json", "csv"];
+var VALID_MODES = ["auto", "online", "local"];
+function validateConfig(config, filePath) {
+  if (config.policy !== void 0) {
+    if (typeof config.policy !== "string" || !VALID_POLICIES.includes(config.policy)) {
+      throw new Error(
+        `Invalid preship-config at ${filePath}:
+  'policy' must be one of: ${VALID_POLICIES.join(", ")}, got '${config.policy}'.
+  See https://github.com/cyfoxinc/preship for config docs.`
+      );
+    }
+  }
+  if (config.output !== void 0) {
+    if (typeof config.output !== "string" || !VALID_OUTPUTS.includes(config.output)) {
+      throw new Error(
+        `Invalid preship-config at ${filePath}:
+  'output' must be one of: ${VALID_OUTPUTS.join(", ")}, got '${config.output}'.
+  See https://github.com/cyfoxinc/preship for config docs.`
+      );
+    }
+  }
+  for (const field of ["reject", "warn", "allow"]) {
+    if (config[field] !== void 0) {
+      if (!Array.isArray(config[field])) {
+        throw new Error(
+          `Invalid preship-config at ${filePath}:
+  '${field}' must be an array of strings, got ${typeof config[field]}.
+  See https://github.com/cyfoxinc/preship for config docs.`
+        );
+      }
+      for (const item of config[field]) {
+        if (typeof item !== "string") {
+          throw new Error(
+            `Invalid preship-config at ${filePath}:
+  '${field}' must contain only strings, found ${typeof item}.
+  See https://github.com/cyfoxinc/preship for config docs.`
+          );
+        }
+      }
+    }
+  }
+  if (config.flagUnknown !== void 0 && typeof config.flagUnknown !== "boolean") {
+    throw new Error(
+      `Invalid preship-config at ${filePath}:
+  'flagUnknown' must be a boolean, got ${typeof config.flagUnknown}.
+  See https://github.com/cyfoxinc/preship for config docs.`
+    );
+  }
+  if (config.scanDevDependencies !== void 0 && typeof config.scanDevDependencies !== "boolean") {
+    throw new Error(
+      `Invalid preship-config at ${filePath}:
+  'scanDevDependencies' must be a boolean, got ${typeof config.scanDevDependencies}.
+  See https://github.com/cyfoxinc/preship for config docs.`
+    );
+  }
+  if (config.exceptions !== void 0) {
+    if (!Array.isArray(config.exceptions)) {
+      throw new Error(
+        `Invalid preship-config at ${filePath}:
+  'exceptions' must be an array, got ${typeof config.exceptions}.
+  See https://github.com/cyfoxinc/preship for config docs.`
+      );
+    }
+    for (const entry of config.exceptions) {
+      if (typeof entry !== "object" || entry === null) {
+        throw new Error(
+          `Invalid preship-config at ${filePath}:
+  Each entry in 'exceptions' must be an object with 'package' and 'reason' fields.
+  See https://github.com/cyfoxinc/preship for config docs.`
+        );
+      }
+      const e = entry;
+      if (typeof e.package !== "string" || typeof e.reason !== "string") {
+        throw new Error(
+          `Invalid preship-config at ${filePath}:
+  Each exception must have 'package' (string) and 'reason' (string) fields.
+  See https://github.com/cyfoxinc/preship for config docs.`
+        );
+      }
+    }
+  }
+  if (config.mode !== void 0) {
+    if (typeof config.mode !== "string" || !VALID_MODES.includes(config.mode)) {
+      throw new Error(
+        `Invalid preship-config at ${filePath}:
+  'mode' must be one of: ${VALID_MODES.join(", ")}, got '${config.mode}'.
+  See https://github.com/cyfoxinc/preship for config docs.`
+      );
+    }
+  }
+  if (config.networkTimeout !== void 0) {
+    if (typeof config.networkTimeout !== "number" || config.networkTimeout <= 0) {
+      throw new Error(
+        `Invalid preship-config at ${filePath}:
+  'networkTimeout' must be a positive number (milliseconds), got '${config.networkTimeout}'.
+  See https://github.com/cyfoxinc/preship for config docs.`
+      );
+    }
+  }
+  if (config.networkConcurrency !== void 0) {
+    if (typeof config.networkConcurrency !== "number" || config.networkConcurrency <= 0 || !Number.isInteger(config.networkConcurrency)) {
+      throw new Error(
+        `Invalid preship-config at ${filePath}:
+  'networkConcurrency' must be a positive integer, got '${config.networkConcurrency}'.
+  See https://github.com/cyfoxinc/preship for config docs.`
+      );
+    }
+  }
+  if (config.cache !== void 0 && typeof config.cache !== "boolean") {
+    throw new Error(
+      `Invalid preship-config at ${filePath}:
+  'cache' must be a boolean, got ${typeof config.cache}.
+  See https://github.com/cyfoxinc/preship for config docs.`
+    );
+  }
+  if (config.cacheTTL !== void 0) {
+    if (typeof config.cacheTTL !== "number" || config.cacheTTL <= 0) {
+      throw new Error(
+        `Invalid preship-config at ${filePath}:
+  'cacheTTL' must be a positive number (seconds), got '${config.cacheTTL}'.
+  See https://github.com/cyfoxinc/preship for config docs.`
+      );
+    }
+  }
+  if (config.scanTimeout !== void 0) {
+    if (typeof config.scanTimeout !== "number" || config.scanTimeout < 0) {
+      throw new Error(
+        `Invalid preship-config at ${filePath}:
+  'scanTimeout' must be a non-negative number (milliseconds, 0 = disabled), got '${config.scanTimeout}'.
+  See https://github.com/cyfoxinc/preship for config docs.`
+      );
+    }
+  }
+  return config;
+}
+function getDefaultConfig() {
+  return {
+    policy: "commercial-safe",
+    flagUnknown: true,
+    scanDevDependencies: false,
+    output: "table",
+    exceptions: [],
+    mode: "auto",
+    networkTimeout: 5e3,
+    networkConcurrency: 10,
+    cache: true,
+    cacheTTL: 604800,
+    // 7 days in seconds
+    scanTimeout: 6e4
+    // 60 seconds in ms (0 = disabled)
+  };
+}
+function loadConfig(projectPath) {
+  for (const filename of CONFIG_FILENAMES) {
+    const filePath = path.join(projectPath, filename);
+    if (!fs.existsSync(filePath)) {
+      continue;
+    }
+    const content = fs.readFileSync(filePath, "utf-8");
+    let parsed;
+    if (filename.endsWith(".json")) {
+      try {
+        parsed = JSON.parse(content);
+      } catch {
+        throw new Error(
+          `Failed to parse ${filePath}: Invalid JSON.
+  The config file may be corrupted. Check syntax and try again.`
+        );
+      }
+    } else {
+      try {
+        parsed = yaml.load(content);
+      } catch {
+        throw new Error(
+          `Failed to parse ${filePath}: Invalid YAML.
+  The config file may be corrupted. Check syntax and try again.`
+        );
+      }
+    }
+    if (parsed === null || parsed === void 0 || typeof parsed !== "object") {
+      return getDefaultConfig();
+    }
+    const validated = validateConfig(parsed, filePath);
+    const defaults = getDefaultConfig();
+    return {
+      ...defaults,
+      ...validated,
+      exceptions: validated.exceptions ?? defaults.exceptions
+    };
+  }
+  return getDefaultConfig();
+}
+
+// src/detector.ts
+var fs2 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var LOCK_FILES = [
+  { filename: "package-lock.json", type: "npm" },
+  { filename: "yarn.lock", type: "yarn" },
+  { filename: "pnpm-lock.yaml", type: "pnpm" }
+];
+function detectFramework(packageJsonPath) {
+  try {
+    const content = fs2.readFileSync(packageJsonPath, "utf-8");
+    const pkg = JSON.parse(content);
+    const allDeps = {
+      ...pkg.dependencies || {},
+      ...pkg.devDependencies || {}
+    };
+    if (allDeps["next"]) return "nextjs";
+    if (allDeps["react"]) return "react";
+    if (allDeps["express"]) return "express";
+    if (allDeps["fastify"]) return "fastify";
+    if (allDeps["@nestjs/core"] || allDeps["nestjs"]) return "nestjs";
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function detectProjects(rootPath) {
+  const absRoot = path2.resolve(rootPath);
+  const packageJsonPath = path2.join(absRoot, "package.json");
+  if (!fs2.existsSync(packageJsonPath)) {
+    throw new Error(
+      `No package.json found in ${absRoot}.
+  PreShip needs a Node.js project to scan.
+  Make sure you're running from the project root.`
+    );
+  }
+  const detected = [];
+  for (const entry of LOCK_FILES) {
+    const lockFilePath = path2.join(absRoot, entry.filename);
+    if (fs2.existsSync(lockFilePath)) {
+      detected.push({
+        type: entry.type,
+        path: absRoot,
+        lockFile: lockFilePath,
+        framework: detectFramework(packageJsonPath)
+      });
+    }
+  }
+  if (detected.length === 0) {
+    throw new Error(
+      `No supported lock file found in ${absRoot}.
+  PreShip needs a lock file to scan dependencies.
+  Run 'npm install', 'yarn install', or 'pnpm install' first.`
+    );
+  }
+  return [detected[0]];
+}
+
+// src/parsers/npm.ts
+var fs3 = __toESM(require("fs"));
+function parseNpmLockfile(lockfilePath, packageJsonPath) {
+  let lockContent;
+  try {
+    lockContent = fs3.readFileSync(lockfilePath, "utf-8");
+  } catch {
+    throw new Error(
+      `Failed to read ${lockfilePath}.
+  The lock file may be missing or corrupted. Try running 'npm install'.`
+    );
+  }
+  let lockfile;
+  try {
+    lockfile = JSON.parse(lockContent);
+  } catch {
+    throw new Error(
+      `Failed to parse ${lockfilePath}: Invalid JSON.
+  The lock file may be corrupted. Try deleting it and running 'npm install' again.`
+    );
+  }
+  let pkgJson;
+  try {
+    pkgJson = JSON.parse(fs3.readFileSync(packageJsonPath, "utf-8"));
+  } catch {
+    throw new Error(
+      `Failed to read or parse ${packageJsonPath}.
+  Make sure package.json exists and is valid JSON.`
+    );
+  }
+  const directDeps = new Set(Object.keys(pkgJson.dependencies || {}));
+  const directDevDeps = new Set(Object.keys(pkgJson.devDependencies || {}));
+  const version = lockfile.lockfileVersion ?? 1;
+  if (version >= 2 && lockfile.packages) {
+    return parseV2Packages(lockfile.packages, directDeps, directDevDeps);
+  }
+  if (lockfile.dependencies) {
+    return parseV1Dependencies(lockfile.dependencies, directDeps, directDevDeps);
+  }
+  return [];
+}
+function parseV2Packages(packages, directDeps, directDevDeps) {
+  const results = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [key, entry] of Object.entries(packages)) {
+    if (key === "") continue;
+    if (!key.startsWith("node_modules/")) continue;
+    const parts = key.split("node_modules/");
+    const name = parts[parts.length - 1];
+    if (!name || !entry.version) continue;
+    const dedupKey = `${name}@${entry.version}`;
+    if (seen.has(dedupKey)) continue;
+    seen.add(dedupKey);
+    const isDirect = directDeps.has(name) || directDevDeps.has(name);
+    const isDevDependency = directDevDeps.has(name) && !directDeps.has(name);
+    results.push({
+      name,
+      version: entry.version,
+      isDirect,
+      isDevDependency
+    });
+  }
+  return results;
+}
+function parseV1Dependencies(dependencies, directDeps, directDevDeps) {
+  const results = [];
+  function walk(deps) {
+    for (const [name, entry] of Object.entries(deps)) {
+      const isDirect = directDeps.has(name) || directDevDeps.has(name);
+      const isDevDependency = directDevDeps.has(name) && !directDeps.has(name);
+      results.push({
+        name,
+        version: entry.version,
+        isDirect,
+        isDevDependency
+      });
+      if (entry.dependencies) {
+        walk(entry.dependencies);
+      }
+    }
+  }
+  walk(dependencies);
+  return results;
+}
+
+// src/parsers/yarn.ts
+var fs4 = __toESM(require("fs"));
+function parseYarnLockfile(lockfilePath, packageJsonPath) {
+  let lockContent;
+  try {
+    lockContent = fs4.readFileSync(lockfilePath, "utf-8");
+  } catch {
+    throw new Error(
+      `Failed to read ${lockfilePath}.
+  The lock file may be missing or corrupted. Try running 'yarn install'.`
+    );
+  }
+  let pkgJson;
+  try {
+    pkgJson = JSON.parse(fs4.readFileSync(packageJsonPath, "utf-8"));
+  } catch {
+    throw new Error(
+      `Failed to read or parse ${packageJsonPath}.
+  Make sure package.json exists and is valid JSON.`
+    );
+  }
+  const directDeps = new Set(Object.keys(pkgJson.dependencies || {}));
+  const directDevDeps = new Set(Object.keys(pkgJson.devDependencies || {}));
+  const isV2 = lockContent.includes("__metadata:");
+  if (isV2) {
+    return parseYarnV2(lockContent, directDeps, directDevDeps);
+  }
+  return parseYarnV1(lockContent, directDeps, directDevDeps);
+}
+function extractPackageName(specifier) {
+  const spec = specifier.replace(/^"/, "").replace(/"$/, "");
+  if (spec.startsWith("@")) {
+    const idx2 = spec.indexOf("@", 1);
+    return idx2 === -1 ? spec : spec.substring(0, idx2);
+  }
+  const idx = spec.indexOf("@");
+  return idx === -1 ? spec : spec.substring(0, idx);
+}
+function extractPackageNameV2(specifier) {
+  const spec = specifier.replace(/^"/, "").replace(/"$/, "");
+  if (spec.startsWith("@")) {
+    const idx2 = spec.indexOf("@", 1);
+    if (idx2 === -1) return spec;
+    return spec.substring(0, idx2);
+  }
+  const idx = spec.indexOf("@");
+  return idx === -1 ? spec : spec.substring(0, idx);
+}
+function parseYarnV1(content, directDeps, directDevDeps) {
+  const results = [];
+  const seen = /* @__PURE__ */ new Set();
+  const lines = content.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line || line.startsWith("#") || line.trim() === "") {
+      i++;
+      continue;
+    }
+    if (!line.startsWith(" ") && line.endsWith(":")) {
+      const specLine = line.replace(/:$/, "").trim().replace(/^"/, "").replace(/"$/, "");
+      const firstSpec = specLine.split(",")[0].trim();
+      const name = extractPackageName(firstSpec);
+      let version;
+      let j = i + 1;
+      while (j < lines.length && lines[j].startsWith(" ")) {
+        const vMatch = lines[j].match(/^\s+version\s+"?([^"\s]+)"?/);
+        if (vMatch) {
+          version = vMatch[1];
+          break;
+        }
+        j++;
+      }
+      if (name && version) {
+        const dedupKey = `${name}@${version}`;
+        if (!seen.has(dedupKey)) {
+          seen.add(dedupKey);
+          const isDirect = directDeps.has(name) || directDevDeps.has(name);
+          const isDevDependency = directDevDeps.has(name) && !directDeps.has(name);
+          results.push({ name, version, isDirect, isDevDependency });
+        }
+      }
+      i = j > i ? j : i + 1;
+    } else {
+      i++;
+    }
+  }
+  return results;
+}
+function parseYarnV2(content, directDeps, directDevDeps) {
+  const results = [];
+  const seen = /* @__PURE__ */ new Set();
+  const lines = content.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line || line.startsWith("#") || line.trim() === "") {
+      i++;
+      continue;
+    }
+    if (line.startsWith("__metadata:")) {
+      i++;
+      while (i < lines.length && lines[i].startsWith(" ")) i++;
+      continue;
+    }
+    if (!line.startsWith(" ") && line.endsWith(":")) {
+      const specLine = line.replace(/:$/, "").trim().replace(/^"/, "").replace(/"$/, "");
+      const firstSpec = specLine.split(",")[0].trim();
+      const name = extractPackageNameV2(firstSpec);
+      let version;
+      let j = i + 1;
+      while (j < lines.length && lines[j].startsWith(" ")) {
+        const vMatch = lines[j].match(/^\s+version:\s+"?([^"\s]+)"?/);
+        if (vMatch) {
+          version = vMatch[1];
+          break;
+        }
+        j++;
+      }
+      if (name && version) {
+        const dedupKey = `${name}@${version}`;
+        if (!seen.has(dedupKey)) {
+          seen.add(dedupKey);
+          const isDirect = directDeps.has(name) || directDevDeps.has(name);
+          const isDevDependency = directDevDeps.has(name) && !directDeps.has(name);
+          results.push({ name, version, isDirect, isDevDependency });
+        }
+      }
+      i = j > i ? j : i + 1;
+    } else {
+      i++;
+    }
+  }
+  return results;
+}
+
+// src/parsers/pnpm.ts
+var fs5 = __toESM(require("fs"));
+var yaml2 = __toESM(require("js-yaml"));
+function parsePnpmLockfile(lockfilePath, packageJsonPath) {
+  let lockContent;
+  try {
+    lockContent = fs5.readFileSync(lockfilePath, "utf-8");
+  } catch {
+    throw new Error(
+      `Failed to read ${lockfilePath}.
+  The lock file may be missing or corrupted. Try running 'pnpm install'.`
+    );
+  }
+  let lockfile;
+  try {
+    lockfile = yaml2.load(lockContent);
+  } catch {
+    throw new Error(
+      `Failed to parse ${lockfilePath}: Invalid YAML.
+  The lock file may be corrupted. Try deleting it and running 'pnpm install' again.`
+    );
+  }
+  if (!lockfile || !lockfile.packages) {
+    return [];
+  }
+  let pkgJson;
+  try {
+    pkgJson = JSON.parse(fs5.readFileSync(packageJsonPath, "utf-8"));
+  } catch {
+    throw new Error(
+      `Failed to read or parse ${packageJsonPath}.
+  Make sure package.json exists and is valid JSON.`
+    );
+  }
+  const directDeps = new Set(Object.keys(pkgJson.dependencies || {}));
+  const directDevDeps = new Set(Object.keys(pkgJson.devDependencies || {}));
+  const version = parseLockfileVersion(lockfile.lockfileVersion);
+  const results = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [key] of Object.entries(lockfile.packages)) {
+    const parsed = parsePackageKey(key, version);
+    if (!parsed) continue;
+    const { name, pkgVersion } = parsed;
+    const dedupKey = `${name}@${pkgVersion}`;
+    if (seen.has(dedupKey)) continue;
+    seen.add(dedupKey);
+    const isDirect = directDeps.has(name) || directDevDeps.has(name);
+    const isDevDependency = directDevDeps.has(name) && !directDeps.has(name);
+    results.push({
+      name,
+      version: pkgVersion,
+      isDirect,
+      isDevDependency
+    });
+  }
+  return results;
+}
+function parseLockfileVersion(version) {
+  if (version === void 0) return 5;
+  const v = typeof version === "string" ? parseFloat(version) : version;
+  return isNaN(v) ? 5 : v;
+}
+function parsePackageKey(key, version) {
+  if (version >= 9 || !key.startsWith("/") && key.includes("@")) {
+    return parseV9Key(key);
+  }
+  return parseV5Key(key);
+}
+function parseV9Key(key) {
+  if (key.startsWith("@")) {
+    const idx2 = key.indexOf("@", 1);
+    if (idx2 === -1) return null;
+    const name2 = key.substring(0, idx2);
+    const pkgVersion2 = key.substring(idx2 + 1);
+    if (!name2 || !pkgVersion2) return null;
+    return { name: name2, pkgVersion: pkgVersion2 };
+  }
+  const idx = key.indexOf("@");
+  if (idx === -1) return null;
+  const name = key.substring(0, idx);
+  const pkgVersion = key.substring(idx + 1);
+  if (!name || !pkgVersion) return null;
+  return { name, pkgVersion };
+}
+function parseV5Key(key) {
+  if (!key.startsWith("/")) return null;
+  const withoutSlash = key.substring(1);
+  if (withoutSlash.startsWith("@")) {
+    const parts2 = withoutSlash.split("/");
+    if (parts2.length < 3) return null;
+    const name2 = `${parts2[0]}/${parts2[1]}`;
+    const pkgVersion2 = parts2[2];
+    if (!pkgVersion2) return null;
+    return { name: name2, pkgVersion: pkgVersion2 };
+  }
+  const parts = withoutSlash.split("/");
+  if (parts.length < 2) return null;
+  const name = parts[0];
+  const pkgVersion = parts[1];
+  if (!name || !pkgVersion) return null;
+  return { name, pkgVersion };
+}
+
+// src/cache.ts
+var crypto = __toESM(require("crypto"));
+var fs6 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+var KEY_FILENAME = ".preship-key";
+var ALGORITHM = "aes-256-cbc";
+var IV_LENGTH = 16;
+function getOrCreateKey(projectPath) {
+  const keyPath = path3.join(projectPath, KEY_FILENAME);
+  try {
+    if (fs6.existsSync(keyPath)) {
+      const hex = fs6.readFileSync(keyPath, "utf-8").trim();
+      if (hex.length === 64) {
+        return Buffer.from(hex, "hex");
+      }
+    }
+  } catch {
+  }
+  const key = crypto.randomBytes(32);
+  try {
+    fs6.writeFileSync(keyPath, key.toString("hex"), { mode: 384 });
+  } catch {
+  }
+  return key;
+}
+function encrypt(data, key) {
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  let encrypted = cipher.update(data, "utf-8", "hex");
+  encrypted += cipher.final("hex");
+  return `${iv.toString("hex")}:${encrypted}`;
+}
+function decrypt(encrypted, key) {
+  const separatorIndex = encrypted.indexOf(":");
+  if (separatorIndex === -1) {
+    throw new Error("Invalid encrypted format");
+  }
+  const ivHex = encrypted.substring(0, separatorIndex);
+  const cipherHex = encrypted.substring(separatorIndex + 1);
+  const iv = Buffer.from(ivHex, "hex");
+  if (iv.length !== IV_LENGTH) {
+    throw new Error("Invalid IV length");
+  }
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+  let decrypted = decipher.update(cipherHex, "hex", "utf-8");
+  decrypted += decipher.final("utf-8");
+  return decrypted;
+}
+function cacheKey(packageName, version) {
+  return `${packageName}@${version}`;
+}
+function createEmptyCache() {
+  return { version: 1, entries: {} };
+}
+function loadCache(cacheFilePath, key) {
+  try {
+    if (!fs6.existsSync(cacheFilePath)) {
+      return createEmptyCache();
+    }
+    const encryptedContent = fs6.readFileSync(cacheFilePath, "utf-8").trim();
+    if (!encryptedContent) {
+      return createEmptyCache();
+    }
+    const jsonStr = decrypt(encryptedContent, key);
+    const parsed = JSON.parse(jsonStr);
+    if (!parsed || parsed.version !== 1 || typeof parsed.entries !== "object") {
+      return createEmptyCache();
+    }
+    return parsed;
+  } catch {
+    return createEmptyCache();
+  }
+}
+function saveCache(cacheFilePath, cache, key) {
+  try {
+    const jsonStr = JSON.stringify(cache);
+    const encrypted = encrypt(jsonStr, key);
+    const tmpPath = cacheFilePath + ".tmp";
+    fs6.writeFileSync(tmpPath, encrypted, "utf-8");
+    fs6.renameSync(tmpPath, cacheFilePath);
+  } catch {
+  }
+}
+function getCacheEntry(cache, packageName, version, ttlSeconds) {
+  const key = cacheKey(packageName, version);
+  const entry = cache.entries[key];
+  if (!entry) {
+    return null;
+  }
+  const ageSeconds = (Date.now() - entry.cachedAt) / 1e3;
+  if (ageSeconds >= ttlSeconds) {
+    return null;
+  }
+  return entry;
+}
+function setCacheEntry(cache, packageName, version, license, licenseSource) {
+  const key = cacheKey(packageName, version);
+  cache.entries[key] = {
+    license,
+    licenseSource,
+    cachedAt: Date.now()
+  };
+}
+
+// src/rate-limiter.ts
+function createEmptyState() {
+  return {
+    remaining: null,
+    limit: null,
+    resetAt: null,
+    retryAfterMs: null,
+    blocked: false
+  };
+}
+var AdaptiveRateLimiter = class {
+  githubState;
+  npmState;
+  config;
+  constructor(config) {
+    this.githubState = createEmptyState();
+    this.npmState = createEmptyState();
+    this.config = {
+      slowdownThreshold: config?.slowdownThreshold ?? 0.2,
+      maxDelay: config?.maxDelay ?? 2e3
+    };
+  }
+  /**
+   * Update rate-limit state from response headers.
+   * Call after every fetch to either source.
+   *
+   * Reads: X-RateLimit-Remaining, X-RateLimit-Limit, X-RateLimit-Reset, Retry-After
+   */
+  updateFromResponse(source, response) {
+    const state = source === "github" ? this.githubState : this.npmState;
+    const remaining = response.headers.get("X-RateLimit-Remaining");
+    const limit = response.headers.get("X-RateLimit-Limit");
+    const reset = response.headers.get("X-RateLimit-Reset");
+    const retryAfter = response.headers.get("Retry-After");
+    if (remaining !== null) {
+      const parsed = parseInt(remaining, 10);
+      if (!isNaN(parsed)) state.remaining = parsed;
+    }
+    if (limit !== null) {
+      const parsed = parseInt(limit, 10);
+      if (!isNaN(parsed)) state.limit = parsed;
+    }
+    if (reset !== null) {
+      const parsed = parseInt(reset, 10);
+      if (!isNaN(parsed)) state.resetAt = parsed;
+    }
+    if (retryAfter !== null) {
+      const seconds = parseInt(retryAfter, 10);
+      if (!isNaN(seconds) && seconds > 0) {
+        state.retryAfterMs = seconds * 1e3;
+      }
+    }
+    if (response.status === 403 && state.remaining === 0) {
+      state.blocked = true;
+    }
+  }
+  /**
+   * Wait if necessary before making the next request.
+   *
+   * Returns true if OK to proceed, false if the source is hard-blocked.
+   *
+   * Delay logic:
+   * 1. If blocked → return false
+   * 2. If Retry-After is set → wait that exact duration
+   * 3. If remaining/limit < threshold → proportional delay
+   * 4. Otherwise → no delay
+   */
+  async waitIfNeeded(source) {
+    const state = source === "github" ? this.githubState : this.npmState;
+    if (state.blocked) {
+      return false;
+    }
+    if (state.retryAfterMs !== null && state.retryAfterMs > 0) {
+      const delay = state.retryAfterMs;
+      state.retryAfterMs = null;
+      await this.delay(delay);
+      return true;
+    }
+    if (state.remaining !== null && state.limit !== null && state.limit > 0) {
+      const ratio = state.remaining / state.limit;
+      if (ratio < this.config.slowdownThreshold) {
+        const progress = 1 - ratio / this.config.slowdownThreshold;
+        const delayMs = Math.round(this.config.maxDelay * progress);
+        if (delayMs > 0) {
+          await this.delay(delayMs);
+        }
+      }
+    }
+    return true;
+  }
+  /**
+   * Check if a source is currently hard-blocked.
+   */
+  isBlocked(source) {
+    const state = source === "github" ? this.githubState : this.npmState;
+    return state.blocked;
+  }
+  /**
+   * Get the current state for a source (for testing/inspection).
+   */
+  getState(source) {
+    return source === "github" ? { ...this.githubState } : { ...this.npmState };
+  }
+  /**
+   * Reset all rate-limit state. Call at start of each scan run.
+   */
+  reset() {
+    this.githubState = createEmptyState();
+    this.npmState = createEmptyState();
+  }
+  delay(ms) {
+    return new Promise((resolve2) => setTimeout(resolve2, ms));
+  }
+};
+
+// src/scan-timeout.ts
+function createScanTimeoutController(timeout) {
+  const topController = new AbortController();
+  let timedOut = false;
+  let scanTimeoutId;
+  if (timeout && timeout > 0) {
+    scanTimeoutId = setTimeout(() => {
+      timedOut = true;
+      topController.abort();
+    }, timeout);
+  }
+  return {
+    signal: topController.signal,
+    isTimedOut() {
+      return timedOut;
+    },
+    createRequestController(perRequestTimeout) {
+      const child = new AbortController();
+      const requestTimeoutId = setTimeout(() => child.abort(), perRequestTimeout);
+      if (topController.signal.aborted) {
+        child.abort();
+      }
+      const onScanAbort = () => {
+        child.abort();
+      };
+      if (!topController.signal.aborted) {
+        topController.signal.addEventListener("abort", onScanAbort, { once: true });
+      }
+      const cleanup = () => {
+        clearTimeout(requestTimeoutId);
+        topController.signal.removeEventListener("abort", onScanAbort);
+      };
+      return { controller: child, cleanup };
+    },
+    dispose() {
+      if (scanTimeoutId !== void 0) {
+        clearTimeout(scanTimeoutId);
+        scanTimeoutId = void 0;
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AdaptiveRateLimiter,
+  cacheKey,
+  createEmptyCache,
+  createScanTimeoutController,
+  detectProjects,
+  getCacheEntry,
+  getOrCreateKey,
+  loadCache,
+  loadConfig,
+  parseNpmLockfile,
+  parsePnpmLockfile,
+  parseYarnLockfile,
+  saveCache,
+  setCacheEntry
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@preship/core",
+  "version": "1.0.0",
+  "description": "Core infrastructure for PreShip — types, config, detection, parsing, caching, and rate limiting",
+  "author": "Cyfox Inc.",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --dts --clean",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "glob": "^10.5.0",
+    "js-yaml": "^4.1.1",
+    "spdx-expression-parse": "^4.0.0",
+    "spdx-license-list": "^6.11.0"
+  }
+}