@dependably/npm-check 1.7.0

package/src/pnpm-format.js

@@ -0,0 +1,229 @@
+// src/pnpm-format.js
+// pnpm-lock.yaml support. pnpm's lockfile is a different shape from npm's:
+//   - YAML, not JSON (`lockfileVersion` is a string like '9.0')
+//   - `importers:` declares each workspace's direct deps (the root is the '.' importer)
+//   - `packages:` is keyed by `name@version` (not by install path) and carries the
+//     `resolution.integrity` we verify against the registry
+//   - registry packages store NO `resolved` tarball URL — the registry is implied by
+//     config (.npmrc), so we resolve the per-package registry base from that instead
+//     of parsing it out of a URL the way the npm path does.
+//
+// This module gives the rest of the toolkit a uniform view: forEachPnpmPackageEntry
+// emits the SAME callback shape as format-library's npm walker (so the integrity /
+// vuln / deprecation checkers iterate it unchanged), plus a precomputed `registryBase`
+// and a normalized `node`.
+import { DEFAULT_REGISTRY } from './integrity.js';
+
+// Strip trailing slashes without a regex (linear scan, no backtracking).
+function stripTrailingSlash(url) {
+  let base = url;
+  while (base.endsWith('/')) base = base.slice(0, -1);
+  return base;
+}
+
+/**
+ * Resolve the registry base for a pnpm package from the project's registry config.
+ * Scoped names honour a matching `@scope:registry`; everything else uses the default
+ * `registry`, falling back to the public npm registry. Preserves private-registry
+ * support without a `resolved` URL to parse.
+ * @param {string|null} name - Real package name (may be scoped)
+ * @param {object} registryConfig - { registry, scopedRegistries }
+ * @returns {string} Registry base URL
+ */
+export function resolvePnpmRegistryBase(name, registryConfig = {}) {
+  const { registry = DEFAULT_REGISTRY, scopedRegistries = {} } = registryConfig;
+  if (name && name.startsWith('@')) {
+    const slash = name.indexOf('/');
+    const scope = slash === -1 ? name : name.slice(0, slash);
+    if (scopedRegistries[scope]) return stripTrailingSlash(scopedRegistries[scope]);
+  }
+  return stripTrailingSlash(registry || DEFAULT_REGISTRY);
+}
+
+/**
+ * Split a pnpm depPath into { name, version }. Handles every pnpm key form the
+ * flavor layer routes here:
+ *   - v9 (`lockfileVersion '9.0'`):   `lodash@4.17.21`, `@scope/pkg@1.0.0`
+ *   - v6 (`'6.0'`, pnpm 8):           `/lodash@4.17.21`, `/@scope/pkg@1.0.0`
+ *   - v5 (`'5.x'`, pnpm 6-7):         `/lodash/4.17.21`, `/@scope/pkg/1.0.0`
+ * plus peer suffixes: paren style `foo@1.0.0(react@18.0.0)` (v6/v9) and the older
+ * v5 underscore style `react-dom/16.13.1_react@16.13.1`.
+ *
+ * The paren peer suffix is stripped FIRST so the inner `@` of a peer (`react@18`)
+ * can't be mistaken for the version separator. A leading `/` (v5/v6 key form) is then
+ * stripped, and the name↔version separator is located past any `@scope/` prefix:
+ * whichever of `@` (v6/v9) or `/` (v5) comes first delimits the version. Local deps
+ * surface as `name@file:../x` / `name@link:../x`.
+ * @param {string} depPath - Key from the pnpm `packages` map
+ * @returns {{ name: string, version: string|null }}
+ */
+export function parsePnpmDepPath(depPath) {
+  // 1. Strip a paren-style peer suffix (`(react@18.0.0)`, v6/v9).
+  const parenIdx = depPath.indexOf('(');
+  let bare = parenIdx === -1 ? depPath : depPath.slice(0, parenIdx);
+
+  // 2. Strip the leading slash of the v5/v6 key forms (v9 keys have none).
+  if (bare.startsWith('/')) bare = bare.slice(1);
+
+  // 3. Locate the name↔version separator past any `@scope/` prefix. The name is
+  //    either `pkg` or `@scope/pkg`, so begin the search after the scope's slash.
+  let searchStart = 0;
+  if (bare.startsWith('@')) {
+    const scopeSlash = bare.indexOf('/');
+    if (scopeSlash !== -1) searchStart = scopeSlash + 1;
+  }
+  const atSep = bare.indexOf('@', searchStart);
+  const slashSep = bare.indexOf('/', searchStart);
+
+  // Slash separator wins only when it exists and precedes any `@` — the v5
+  // `/name/version` form. Its version may carry an underscore peer suffix
+  // (`16.13.1_react@16.13.1`), trimmed here (semver versions never contain `_`,
+  // so this is safe for the slash form).
+  if (slashSep !== -1 && (atSep === -1 || slashSep < atSep)) {
+    let version = bare.slice(slashSep + 1);
+    const underscore = version.indexOf('_');
+    if (underscore !== -1) version = version.slice(0, underscore);
+    return { name: bare.slice(0, slashSep), version: version || null };
+  }
+  // Otherwise `@` separates name from version (v6/v9). `file:`/`link:` versions —
+  // which contain slashes after the `@` — land here and are preserved verbatim.
+  if (atSep > 0) {
+    return { name: bare.slice(0, atSep), version: bare.slice(atSep + 1) || null };
+  }
+  return { name: bare, version: null }; // name with no version / no separator
+}
+
+/**
+ * Classify a pnpm `packages` entry into the boolean flags the checkers already
+ * understand. Only a plain registry package (integrity, semver version, no
+ * tarball/git/local marker) is left verifiable; everything else is flagged so the
+ * existing skip logic in the checkers passes over it.
+ * @param {string} version - Version portion of the depPath
+ * @param {object} entry - The pnpm package entry (with `resolution`)
+ * @returns {{ kind: string, flags: object }}
+ */
+function classifyPnpmPackage(version, entry) {
+  const resolution = (entry && entry.resolution) || {};
+  const flags = { isLink: false, isBundled: false, isGitDep: false, isFileDep: false };
+
+  if (typeof version === 'string' && version.startsWith('link:')) {
+    flags.isLink = true;
+    return { kind: 'link', flags };
+  }
+  if (typeof version === 'string' && (version.startsWith('file:') || resolution.directory)) {
+    flags.isFileDep = true;
+    return { kind: 'file', flags };
+  }
+  if (resolution.type === 'git' || resolution.repo || (typeof version === 'string' && version.startsWith('git'))) {
+    flags.isGitDep = true;
+    return { kind: 'git', flags };
+  }
+  if (resolution.tarball) {
+    // Remote URL-tarball dep — may or may not carry its own `integrity`. pnpm records
+    // BOTH `tarball` and `integrity` for these (a plain registry entry has integrity
+    // and NO tarball). The `version` parsed from the key is the tarball URL, not a
+    // registry version, so no registry advisory/manifest applies — treat like a
+    // file/url dep so the checkers skip it, regardless of integrity.
+    flags.isFileDep = true;
+    return { kind: 'tarball', flags };
+  }
+  if (resolution.integrity) {
+    return { kind: 'registry', flags };
+  }
+  // Unknown / unverifiable shape — flag as file so it is skipped, not mis-checked.
+  flags.isFileDep = true;
+  return { kind: 'file', flags };
+}
+
+/**
+ * Iterate a parsed pnpm-lock.yaml, emitting one info object per importer (root /
+ * workspace) and per `packages` entry. The shape mirrors format-library's npm
+ * walker — { key, entry, name, isRoot, isWorkspaceSource, isLink, isBundled,
+ * isGitDep, isFileDep } — plus `registryBase` and a normalized `node`, so the
+ * downstream checkers iterate npm and pnpm uniformly.
+ *
+ * The registry config is read from `lockfile.__npmCheckMeta` (stamped by the
+ * parser from the sibling .npmrc); absent meta falls back to public-registry
+ * defaults.
+ * @param {object} lockfile - Parsed pnpm lockfile
+ * @param {function} callback - Called with each entry's info
+ */
+// Per-package registry config, read from `lockfile.__npmCheckMeta` (stamped by the
+// parser from the sibling .npmrc); absent meta falls back to public-registry defaults.
+function pnpmRegistryConfig(lockfile) {
+  const meta = lockfile && lockfile.__npmCheckMeta;
+  return {
+    registry: (meta && meta.registry) || DEFAULT_REGISTRY,
+    scopedRegistries: (meta && meta.scopedRegistries) || {}
+  };
+}
+
+// Emit one importer (the root project '.' or a workspace package). These have no
+// integrity to verify; emitting them keeps counts/iteration aligned with the npm
+// root+workspace entries (the checkers skip both).
+function emitPnpmImporter(importerKey, callback) {
+  const isRoot = importerKey === '.';
+  const node = { name: null, version: null, integrity: null, registryBase: null, kind: isRoot ? 'root' : 'workspace', path: importerKey };
+  callback({
+    key: importerKey,
+    entry: {},
+    name: null,
+    isRoot,
+    isWorkspaceSource: !isRoot,
+    isLink: false,
+    isBundled: false,
+    isGitDep: false,
+    isFileDep: false,
+    registryBase: null,
+    node
+  });
+}
+
+// Emit one resolved `packages` entry (keyed by `name@version`).
+function emitPnpmPackage(depPath, entry, registryConfig, callback) {
+  const { name, version } = parsePnpmDepPath(depPath);
+  const { kind, flags } = classifyPnpmPackage(version, entry);
+  const resolution = (entry && entry.resolution) || {};
+  const integrity = resolution.integrity || null;
+  const registryBase = kind === 'registry' ? resolvePnpmRegistryBase(name, registryConfig) : null;
+
+  // Synthesize an npm-shaped `entry` so the existing checkers read it unchanged:
+  // version + integrity are the fields they consult; `resolved` is null for pnpm
+  // registry deps (the registry comes from `registryBase`, not a URL).
+  const synthEntry = {
+    version: version || undefined,
+    integrity: integrity || undefined,
+    resolved: resolution.tarball || undefined,
+    deprecated: entry && entry.deprecated
+  };
+
+  callback({
+    key: depPath,
+    entry: synthEntry,
+    name,
+    isRoot: false,
+    isWorkspaceSource: false,
+    isLink: flags.isLink,
+    isBundled: flags.isBundled,
+    isGitDep: flags.isGitDep,
+    isFileDep: flags.isFileDep,
+    registryBase,
+    node: { name, version: version || null, integrity, registryBase, kind, path: depPath }
+  });
+}
+
+export function forEachPnpmPackageEntry(lockfile, callback) {
+  const registryConfig = pnpmRegistryConfig(lockfile);
+
+  // 1. Importers: the root project ('.') and each workspace package.
+  const importers = (lockfile && lockfile.importers) || {};
+  for (const importerKey of Object.keys(importers)) {
+    emitPnpmImporter(importerKey, callback);
+  }
+
+  // 2. Packages: the resolved dependency set, keyed by `name@version`.
+  const packages = (lockfile && lockfile.packages) || {};
+  for (const [depPath, entry] of Object.entries(packages)) {
+    emitPnpmPackage(depPath, entry, registryConfig, callback);
+  }
+}

package/src/pnpm-workspace-validator.js

@@ -0,0 +1,121 @@
+// src/pnpm-workspace-validator.js
+// Validate a project's pnpm-workspace.yaml — the file that, since pnpm 9/10, holds
+// both the workspace package globs AND most pnpm settings that used to live in
+// .npmrc / the package.json `pnpm` field. Same contract as the other validators:
+// validatePnpmWorkspace(contentOrParsed, options) => { valid, errors, warnings, info }.
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+let _yaml = null;
+function loadYaml() {
+  if (!_yaml) _yaml = require('yaml');
+  return _yaml;
+}
+
+export class PnpmWorkspaceValidationError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'PnpmWorkspaceValidationError';
+    this.code = code;
+  }
+}
+
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+
+// Recognized top-level keys and the type each must have. Generous (warn-only on
+// unknowns) rather than exhaustive — pnpm adds settings often.
+const KNOWN_KEYS = {
+  packages: isStringArray,
+  catalog: isPlainObject,
+  catalogs: isPlainObject,
+  overrides: isPlainObject,
+  packageExtensions: isPlainObject,
+  peerDependencyRules: isPlainObject,
+  patchedDependencies: isPlainObject,
+  allowedDeprecatedVersions: isPlainObject,
+  onlyBuiltDependencies: isStringArray,
+  neverBuiltDependencies: isStringArray,
+  ignoredBuiltDependencies: isStringArray,
+  onlyBuiltDependenciesFile: (v) => typeof v === 'string',
+  packageConfigs: isPlainObject,
+  // Common scalar settings that legitimately live here in pnpm 9/10.
+  nodeLinker: (v) => typeof v === 'string',
+  shamefullyHoist: (v) => typeof v === 'boolean',
+  hoistPattern: isStringArray,
+  publicHoistPattern: isStringArray,
+  autoInstallPeers: (v) => typeof v === 'boolean',
+  dedupePeerDependents: (v) => typeof v === 'boolean',
+  strictPeerDependencies: (v) => typeof v === 'boolean',
+  excludeLinksFromLockfile: (v) => typeof v === 'boolean',
+  enablePrePostScripts: (v) => typeof v === 'boolean',
+  virtualStoreDir: (v) => typeof v === 'string',
+  preferWorkspacePackages: (v) => typeof v === 'boolean',
+  linkWorkspacePackages: (v) => typeof v === 'boolean' || typeof v === 'string',
+  saveWorkspaceProtocol: (v) => typeof v === 'boolean' || typeof v === 'string'
+};
+
+const TYPE_LABEL = new Map([
+  [isStringArray, 'an array of strings'],
+  [isPlainObject, 'an object']
+]);
+function expectedLabel(validator) {
+  return TYPE_LABEL.get(validator) || 'the correct type';
+}
+
+/**
+ * Parse pnpm-workspace.yaml content into an object (lazy `yaml` dep). Throws on
+ * malformed YAML so callers can report it as a single structural error.
+ * @param {string} content - Raw file contents
+ * @returns {object} Parsed document (an empty file yields {})
+ */
+export function parsePnpmWorkspace(content) {
+  const data = loadYaml().parse(content);
+  return data == null ? {} : data;
+}
+
+/**
+ * Validate a parsed (or raw-string) pnpm-workspace.yaml.
+ * @param {string|object} input - Raw YAML string or already-parsed object
+ * @param {object} options - { strictMode }
+ * @returns {{ valid, errors, warnings, info }}
+ */
+export function validatePnpmWorkspace(input, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const info = {};
+
+  let doc;
+  if (typeof input === 'string') {
+    try {
+      doc = parsePnpmWorkspace(input);
+    } catch (e) {
+      errors.push(new PnpmWorkspaceValidationError(`invalid YAML in pnpm-workspace.yaml: ${e.message}`, 'PNPM_WS_SYNTAX'));
+      return { valid: false, errors, warnings, info };
+    }
+  } else {
+    doc = input || {};
+  }
+
+  if (!isPlainObject(doc)) {
+    errors.push(new PnpmWorkspaceValidationError('pnpm-workspace.yaml must be a YAML mapping', 'PNPM_WS_NOT_OBJECT'));
+    return { valid: false, errors, warnings, info };
+  }
+
+  info.hasPackages = Array.isArray(doc.packages);
+  info.keys = Object.keys(doc);
+
+  for (const [key, value] of Object.entries(doc)) {
+    const validator = KNOWN_KEYS[key];
+    if (!validator) {
+      warnings.push({ code: 'PNPM_WS_UNKNOWN_KEY', message: `unrecognized pnpm-workspace.yaml key "${key}"` });
+      continue;
+    }
+    if (!validator(value)) {
+      errors.push(new PnpmWorkspaceValidationError(`"${key}" must be ${expectedLabel(validator)}`, 'PNPM_WS_INVALID_TYPE'));
+    }
+  }
+
+  const valid = errors.length === 0 && !(options.strictMode && warnings.length > 0);
+  return { valid, errors, warnings, info };
+}

package/src/progress-reporter.js

@@ -0,0 +1,245 @@
+/**
+ * Progress reporting utilities for long-running operations.
+ * Provides real-time progress updates with time estimates and memory tracking.
+ */
+
+import { EventEmitter } from 'events';
+import { getMemoryStats } from './performance.js';
+
+/**
+ * Progress information object structure
+ * @typedef {Object} ProgressInfo
+ * @property {number} current - Current item count
+ * @property {number} total - Total items
+ * @property {number} percentage - Progress percentage (0-100)
+ * @property {number} elapsed - Milliseconds elapsed
+ * @property {number} estimated - Estimated time remaining (ms)
+ * @property {Object|null} memory - Memory stats if enabled
+ * @property {string} stage - Current operation stage
+ */
+
+/**
+ * ProgressReporter class for tracking operation progress
+ * Supports both callback and event emitter patterns
+ */
+export class ProgressReporter extends EventEmitter {
+  /**
+   * Create a new ProgressReporter
+   * @param {number} total - Total number of items to process
+   * @param {Object} options - Options
+   * @param {Function} options.onProgress - Callback function(progressInfo)
+   * @param {number} options.updateInterval - Update interval in ms (default: 100)
+   * @param {boolean} options.showMemory - Include memory stats (default: false)
+   * @param {string} options.stage - Initial stage name (default: 'Processing')
+   */
+  constructor(total = 0, options = {}) {
+    super();
+    this.total = total;
+    this.current = 0;
+    this.startTime = Date.now();
+    this.lastUpdateTime = this.startTime;
+    this.onProgressCallback = options.onProgress || null;
+    this.updateInterval = options.updateInterval || 100;
+    this.showMemory = options.showMemory || false;
+    this.stage = options.stage || 'Processing';
+    this.finished = false;
+    this.lastReportedPercentage = -1;
+  }
+
+  /**
+   * Update progress to a specific value
+   * @param {number} current - Current item count
+   * @param {string} stage - Optional stage name
+   */
+  update(current, stage = null) {
+    if (this.finished) return;
+
+    this.current = Math.min(current, this.total);
+    if (stage) {
+      this.stage = stage;
+    }
+
+    const now = Date.now();
+    const timeSinceLastUpdate = now - this.lastUpdateTime;
+
+      // If consumers are listening or a callback is provided, report immediately
+      if (this.onProgressCallback || this.listenerCount('progress') > 0) {
+        this._report();
+        this.lastUpdateTime = now;
+        return;
+      }
+
+      // Otherwise throttle updates to avoid overhead
+      if (timeSinceLastUpdate >= this.updateInterval || this.current === this.total) {
+        this._report();
+        this.lastUpdateTime = now;
+      }
+  }
+
+  /**
+   * Increment progress by 1
+   * @param {string} stage - Optional stage name
+   */
+  increment(stage = null) {
+    this.update(this.current + 1, stage);
+  }
+
+  /**
+   * Set total items (useful when total is unknown initially)
+   * @param {number} total - Total number of items
+   */
+  setTotal(total) {
+    this.total = total;
+    // Recalculate and report immediately
+    this._report();
+  }
+
+  /**
+   * Finish progress reporting
+   * @param {string} message - Optional completion message
+   */
+  finish(message = null) {
+    if (this.finished) return;
+
+    this.current = this.total;
+    this.finished = true;
+    this._report(true);
+
+    if (message) {
+      this.emit('complete', message);
+      if (this.onProgressCallback) {
+        this.onProgressCallback(this._getProgressInfo(), message);
+      }
+    }
+  }
+
+  /**
+   * Reset progress reporter
+   * @param {number} total - New total (optional)
+   */
+  reset(total = null) {
+    this.current = 0;
+    this.startTime = Date.now();
+    this.lastUpdateTime = this.startTime;
+    this.finished = false;
+    this.lastReportedPercentage = -1;
+    if (total !== null) {
+      this.total = total;
+    }
+  }
+
+  /**
+   * Get current progress information
+   * @returns {ProgressInfo} Progress information object
+   */
+  _getProgressInfo() {
+    const elapsed = Date.now() - this.startTime;
+    const percentage = this.total > 0
+      ? Math.min(100, Math.round((this.current / this.total) * 100))
+      : 0;
+
+    // Calculate estimated time remaining
+    let estimated = 0;
+    if (this.current > 0 && this.current < this.total) {
+      const rate = this.current / elapsed; // items per ms
+      const remaining = this.total - this.current;
+      estimated = Math.round(remaining / rate);
+    }
+
+    const progressInfo = {
+      current: this.current,
+      total: this.total,
+      percentage,
+      elapsed,
+      estimated,
+      stage: this.stage,
+      memory: null
+    };
+
+    if (this.showMemory) {
+      progressInfo.memory = getMemoryStats();
+    }
+
+    return progressInfo;
+  }
+
+  /**
+   * Report progress (internal)
+   * @param {boolean} force - Force report even if percentage unchanged
+   */
+  _report(force = false) {
+    const progressInfo = this._getProgressInfo();
+
+    // Only report if percentage changed or forced
+    if (force || progressInfo.percentage !== this.lastReportedPercentage) {
+      this.lastReportedPercentage = progressInfo.percentage;
+
+      // Emit event
+      this.emit('progress', progressInfo);
+
+      // Call callback if provided
+      if (this.onProgressCallback) {
+        this.onProgressCallback(progressInfo);
+      }
+    }
+  }
+}
+
+/**
+ * Create a progress reporter with callback
+ * @param {number} total - Total number of items
+ * @param {Object} options - Options (see ProgressReporter constructor)
+ * @returns {ProgressReporter} Progress reporter instance
+ */
+export function createProgressReporter(total, options = {}) {
+  return new ProgressReporter(total, options);
+}
+
+/**
+ * Format progress as a simple text string
+ * @param {ProgressInfo} progress - Progress information
+ * @returns {string} Formatted progress string
+ */
+export function formatProgress(progress) {
+  const { current, total, percentage, elapsed, estimated, stage } = progress;
+
+  const elapsedSec = (elapsed / 1000).toFixed(1);
+  const estimatedSec = estimated > 0 ? (estimated / 1000).toFixed(1) : '?';
+
+  let text = `[${stage}] ${current}/${total} (${percentage}%)`;
+
+  if (elapsed > 0) {
+    text += ` | Elapsed: ${elapsedSec}s`;
+    if (estimated > 0) {
+      text += ` | ETA: ${estimatedSec}s`;
+    }
+  }
+
+  if (progress.memory) {
+    text += ` | Memory: ${progress.memory.heapUsed.toFixed(1)}MB`;
+  }
+
+  return text;
+}
+
+/**
+ * Create a simple progress bar string
+ * @param {ProgressInfo} progress - Progress information
+ * @param {number} width - Bar width in characters (default: 40)
+ * @returns {string} Progress bar string
+ */
+export function createProgressBar(progress, width = 40) {
+  const { percentage } = progress;
+  const filled = Math.round((percentage / 100) * width);
+  const empty = width - filled;
+
+  const bar = '█'.repeat(filled) + '░'.repeat(empty);
+  return `[${bar}] ${percentage}%`;
+}
+
+export default {
+  ProgressReporter,
+  createProgressReporter,
+  formatProgress,
+  createProgressBar
+};