flatlock 1.0.1 → 1.2.0

package/src/parsers/pnpm/index.js

@@ -0,0 +1,289 @@
+/**
+ * @fileoverview pnpm lockfile parser supporting all documented versions
+ *
+ * Supported formats:
+ * - shrinkwrap.yaml v3/v4 (2016-2019): shrinkwrapVersion field
+ * - pnpm-lock.yaml v5.x (2019-2022): lockfileVersion number
+ * - pnpm-lock.yaml v5.4-inlineSpecifiers (experimental): lockfileVersion string
+ * - pnpm-lock.yaml v6.0 (2023): lockfileVersion '6.0'
+ * - pnpm-lock.yaml v9.0 (2024+): lockfileVersion '9.0'
+ *
+ * @module flatlock/parsers/pnpm
+ */
+
+import yaml from 'js-yaml';
+
+import { detectVersion } from './detect.js';
+import { parseSpecShrinkwrap } from './shrinkwrap.js';
+import { parseSpecV5 } from './v5.js';
+import { parseSpecV6Plus } from './v6plus.js';
+
+/** @typedef {import('../types.js').Dependency} Dependency */
+
+// Public API: detectVersion for users who need to inspect lockfile version
+export { detectVersion } from './detect.js';
+
+// Version-specific internals available via 'flatlock/parsers/pnpm/internal'
+
+/**
+ * Parse pnpm package spec to extract name and version.
+ *
+ * This is the unified parser that auto-detects the format based on the spec pattern.
+ * It supports all pnpm lockfile versions without requiring version context.
+ *
+ * Detection heuristics:
+ * 1. If spec contains '(' -> v6+ format (peer deps in parentheses)
+ * 2. If spec contains '@' after position 0 and no '/' after the '@' -> v6+ format
+ * 3. Otherwise -> v5 or earlier format (slash separator)
+ *
+ * @param {string} spec - Package spec from pnpm lockfile
+ * @returns {{ name: string | null, version: string | null }}
+ *
+ * @example
+ * // v5 format - unscoped package
+ * parseSpec('/lodash/4.17.21')
+ * // => { name: 'lodash', version: '4.17.21' }
+ *
+ * @example
+ * // v5 format - scoped package
+ * parseSpec('/@babel/core/7.23.0')
+ * // => { name: '@babel/core', version: '7.23.0' }
+ *
+ * @example
+ * // v5 format - with peer dependency suffix (underscore)
+ * parseSpec('/styled-jsx/3.0.9_react@17.0.2')
+ * // => { name: 'styled-jsx', version: '3.0.9' }
+ *
+ * @example
+ * // v6 format - unscoped package (with leading slash)
+ * parseSpec('/lodash@4.17.21')
+ * // => { name: 'lodash', version: '4.17.21' }
+ *
+ * @example
+ * // v6 format - scoped package
+ * parseSpec('/@babel/core@7.23.0')
+ * // => { name: '@babel/core', version: '7.23.0' }
+ *
+ * @example
+ * // v9 format - unscoped package (no leading slash)
+ * parseSpec('lodash@4.17.21')
+ * // => { name: 'lodash', version: '4.17.21' }
+ *
+ * @example
+ * // v9 format - scoped package (no leading slash)
+ * parseSpec('@babel/core@7.23.0')
+ * // => { name: '@babel/core', version: '7.23.0' }
+ *
+ * @example
+ * // v9 format - with peer dependency suffix (parentheses)
+ * parseSpec('@babel/core@7.23.0(@types/node@20.0.0)')
+ * // => { name: '@babel/core', version: '7.23.0' }
+ *
+ * @example
+ * // v9 format - multiple peer dependencies
+ * parseSpec('@testing-library/react@14.0.0(react-dom@18.2.0)(react@18.2.0)')
+ * // => { name: '@testing-library/react', version: '14.0.0' }
+ *
+ * @example
+ * // Shrinkwrap v3/v4 format - with peer suffix (slash)
+ * parseSpec('/foo/1.0.0/bar@2.0.0')
+ * // => { name: 'foo', version: '1.0.0' }
+ *
+ * @example
+ * // link: protocol - skipped (returns null)
+ * parseSpec('link:packages/my-pkg')
+ * // => { name: null, version: null }
+ *
+ * @example
+ * // file: protocol - skipped (returns null)
+ * parseSpec('file:../local-package')
+ * // => { name: null, version: null }
+ *
+ * @example
+ * // Null input
+ * parseSpec(null)
+ * // => { name: null, version: null }
+ *
+ * @example
+ * // Prerelease version
+ * parseSpec('@verdaccio/ui-theme@6.0.0-6-next.50')
+ * // => { name: '@verdaccio/ui-theme', version: '6.0.0-6-next.50' }
+ */
+export function parseSpec(spec) {
+  // Handle null/undefined input
+  if (spec == null || typeof spec !== 'string') {
+    return { name: null, version: null };
+  }
+
+  // Skip special protocols
+  if (spec.startsWith('link:') || spec.startsWith('file:')) {
+    return { name: null, version: null };
+  }
+
+  // Detect format based on spec pattern
+  // v6+ uses parentheses for peer deps and @ separator
+  // v5 and earlier use _ for peer deps and / separator
+
+  // Check for v6+ parentheses peer suffix
+  if (spec.includes('(')) {
+    return parseSpecV6Plus(spec);
+  }
+
+  // Remove leading slash for analysis
+  const cleaned = spec.startsWith('/') ? spec.slice(1) : spec;
+
+  // Check for v6+ @ separator format
+  // In v6+, the format is name@version where @ separates name from version
+  // We need to find @ that isn't at position 0 (which would be a scope)
+  // And check that it's not part of a v5 peer suffix (which comes after _)
+
+  // First strip any v5 peer suffix for cleaner analysis
+  const withoutV5Peer = cleaned.split('_')[0];
+
+  // Find the last @ in the cleaned string
+  const lastAtIndex = withoutV5Peer.lastIndexOf('@');
+
+  if (lastAtIndex > 0) {
+    // Check if this is v6+ format by seeing if there's a / after the @
+    // In v6+: @babel/core@7.23.0 - the last @ separates name@version
+    // In v5: @babel/core/7.23.0 - no @ after the scope
+
+    const afterAt = withoutV5Peer.slice(lastAtIndex + 1);
+
+    // If there's no / in the part after the last @, it's likely v6+ format
+    // (the part after @ is just the version like "7.23.0")
+    if (!afterAt.includes('/')) {
+      return parseSpecV6Plus(spec);
+    }
+  }
+
+  // Fall back to v5 format (also handles shrinkwrap v3/v4 for basic cases)
+  // Note: shrinkwrap v3/v4 peer suffix with / is handled differently,
+  // but parseSpecV5 will still extract the correct name/version
+  // because it stops at _ (v5) and the shrinkwrap / peer suffix
+  // comes after the version anyway
+
+  return parseSpecV5(spec);
+}
+
+/**
+ * Extract package name from pnpm lockfile key.
+ * Wraps parseSpec to return just the name (consistent with other parsers).
+ *
+ * @param {string} key - pnpm lockfile key
+ * @returns {string | null} Package name
+ *
+ * @example
+ * parseLockfileKey('/@babel/core@7.23.0') // => '@babel/core'
+ * parseLockfileKey('/lodash/4.17.21') // => 'lodash'
+ */
+export function parseLockfileKey(key) {
+  return parseSpec(key).name;
+}
+
+/**
+ * Parse pnpm lockfile (shrinkwrap.yaml, pnpm-lock.yaml v5.x, v6, v9)
+ *
+ * @param {string | object} input - Lockfile content string or pre-parsed object
+ * @param {Object} [_options] - Parser options (unused, reserved for future use)
+ * @returns {Generator<Dependency>}
+ *
+ * @example
+ * // Parse from string
+ * const deps = [...fromPnpmLock(yamlContent)];
+ *
+ * @example
+ * // Parse from pre-parsed object
+ * const lockfile = yaml.load(content);
+ * const deps = [...fromPnpmLock(lockfile)];
+ */
+export function* fromPnpmLock(input, _options = {}) {
+  const lockfile = /** @type {Record<string, any>} */ (
+    typeof input === 'string' ? yaml.load(input) : input
+  );
+
+  // Detect version to determine where to look for packages
+  const detected = detectVersion(lockfile);
+
+  // Select era-specific parser
+  // Each era has different peer suffix formats that parseSpec can't auto-detect
+  const parseSpecForEra =
+    detected.era === 'shrinkwrap'
+      ? parseSpecShrinkwrap
+      : detected.era === 'v5'
+        ? parseSpecV5
+        : parseSpecV6Plus;
+
+  // Get packages object - location varies by version
+  // v5, v6: packages section directly
+  // v9: packages section has metadata, snapshots has relationships
+  // For dependency extraction, we primarily need packages (for resolution info)
+  const packages = lockfile.packages || {};
+
+  // For v9, we should also look at snapshots for additional entries
+  // that might only be in snapshots (peer variants)
+  const snapshots = lockfile.snapshots || {};
+
+  // Track seen packages to avoid duplicates (v9 has same package in both sections)
+  const seen = new Set();
+
+  // Process packages section
+  for (const [spec, pkg] of Object.entries(packages)) {
+    // Skip if we couldn't parse name/version
+    const { name, version } = parseSpecForEra(spec);
+    if (!name || !version) continue;
+
+    // Create dedup key
+    const key = `${name}@${version}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const resolution = pkg.resolution || {};
+    const integrity = resolution.integrity;
+    const resolved = resolution.tarball;
+    const link = spec.startsWith('link:') || resolution.type === 'directory';
+
+    // Skip workspace/link entries - flatlock only cares about external dependencies
+    if (link) continue;
+
+    /** @type {Dependency} */
+    const dep = { name, version };
+    if (integrity) dep.integrity = integrity;
+    if (resolved) dep.resolved = resolved;
+    yield dep;
+  }
+
+  // For v9, also process snapshots for peer variants
+  // (they might have different resolution info)
+  if (detected.era === 'v9') {
+    for (const [spec, _snapshot] of Object.entries(snapshots)) {
+      const { name, version } = parseSpecForEra(spec);
+      if (!name || !version) continue;
+
+      // Create dedup key
+      const key = `${name}@${version}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      // Snapshots don't have resolution info, check if base package exists
+      // The base package key in v9 is just name@version (without peer suffix)
+      const baseKey = `${name}@${version}`;
+      const basePkg = packages[baseKey];
+
+      if (basePkg) {
+        const resolution = basePkg.resolution || {};
+        const integrity = resolution.integrity;
+        const resolved = resolution.tarball;
+
+        /** @type {Dependency} */
+        const dep = { name, version };
+        if (integrity) dep.integrity = integrity;
+        if (resolved) dep.resolved = resolved;
+        yield dep;
+      }
+    }
+  }
+
+  // Note: importers (workspace packages) are intentionally NOT yielded
+  // flatlock only cares about external dependencies
+}

package/src/parsers/pnpm/internal.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Internal/advanced pnpm parser exports
+ *
+ * This module exports version-specific parsing utilities for advanced use cases
+ * such as testing, debugging, or when you need fine-grained control over parsing.
+ *
+ * For normal usage, import from 'flatlock' or 'flatlock/parsers/pnpm' instead.
+ *
+ * @module flatlock/parsers/pnpm/internal
+ */
+
+// Detection utilities
+export {
+  detectVersion,
+  hasLeadingSlash,
+  usesAtSeparator,
+  usesInlineSpecifiers,
+  usesSnapshotsSplit
+} from './detect.js';
+
+// Shrinkwrap v3/v4 (2016-2019)
+export {
+  extractPeerSuffix,
+  hasPeerSuffix,
+  parseSpecShrinkwrap
+} from './shrinkwrap.js';
+
+// v5.x (2019-2022)
+export {
+  extractPeerSuffixV5,
+  hasPeerSuffixV5,
+  parseSpecV5
+} from './v5.js';
+
+// v6+ (2023+)
+export {
+  extractPeerSuffixV6Plus,
+  hasPeerSuffixV6Plus,
+  parsePeerDependencies,
+  parseSpecV6Plus
+} from './v6plus.js';

package/src/parsers/pnpm/shrinkwrap.js

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview Parser for pnpm shrinkwrap.yaml (v3/v4) format
+ *
+ * Shrinkwrap format (2016-2019) characteristics:
+ * - File: shrinkwrap.yaml
+ * - Version field: shrinkwrapVersion (number, typically 3 or 4)
+ * - Package key format: /name/version or /@scope/name/version
+ * - Peer dependency suffix: /peer@ver with ! escaping for scoped packages
+ *   Example: /foo/1.0.0/bar@2.0.0+@scope!qar@3.0.0
+ *
+ * @module flatlock/parsers/pnpm/shrinkwrap
+ */
+
+/**
+ * @typedef {Object} ParsedSpec
+ * @property {string|null} name - The package name (null if unparseable)
+ * @property {string|null} version - The package version (null if unparseable)
+ */
+
+/**
+ * Parse a shrinkwrap.yaml package spec (v3/v4 format).
+ *
+ * Shrinkwrap format uses:
+ * - Slash separator between name and version: /name/version
+ * - Peer dependencies after another slash: /name/version/peer@ver
+ * - Scoped packages: /@scope/name/version
+ * - Scoped peer dependencies use `!` to escape the `@`: `/name/1.0.0/peer@2.0.0+@scope!qar@3.0.0`
+ *
+ * @param {string} spec - Package spec from shrinkwrap.yaml packages section
+ * @returns {ParsedSpec} Parsed name and version
+ *
+ * @example
+ * // Unscoped package
+ * parseSpecShrinkwrap('/lodash/4.17.21')
+ * // => { name: 'lodash', version: '4.17.21' }
+ *
+ * @example
+ * // Scoped package
+ * parseSpecShrinkwrap('/@babel/core/7.23.0')
+ * // => { name: '@babel/core', version: '7.23.0' }
+ *
+ * @example
+ * // With peer dependency suffix
+ * parseSpecShrinkwrap('/foo/1.0.0/bar@2.0.0')
+ * // => { name: 'foo', version: '1.0.0' }
+ *
+ * @example
+ * // With scoped peer dependency (`!` escapes `@`)
+ * parseSpecShrinkwrap('/foo/1.0.0/bar@2.0.0+@scope!qar@3.0.0')
+ * // => { name: 'foo', version: '1.0.0' }
+ *
+ * @example
+ * // Scoped package with peer deps
+ * parseSpecShrinkwrap('/@emotion/styled/10.0.27/react@17.0.2')
+ * // => { name: '@emotion/styled', version: '10.0.27' }
+ *
+ * @example
+ * // Multiple peer dependencies
+ * parseSpecShrinkwrap('/styled-components/5.3.6/react-dom@17.0.2+react@17.0.2')
+ * // => { name: 'styled-components', version: '5.3.6' }
+ *
+ * @example
+ * // Package with hyphenated name
+ * parseSpecShrinkwrap('/string-width/4.2.3')
+ * // => { name: 'string-width', version: '4.2.3' }
+ *
+ * @example
+ * // Scoped package with hyphenated name
+ * parseSpecShrinkwrap('/@babel/helper-compilation-targets/7.23.6')
+ * // => { name: '@babel/helper-compilation-targets', version: '7.23.6' }
+ *
+ * @example
+ * // link: protocol - skipped
+ * parseSpecShrinkwrap('link:packages/my-pkg')
+ * // => { name: null, version: null }
+ *
+ * @example
+ * // file: protocol - skipped
+ * parseSpecShrinkwrap('file:../local-package')
+ * // => { name: null, version: null }
+ *
+ * @example
+ * // Null input
+ * parseSpecShrinkwrap(null)
+ * // => { name: null, version: null }
+ *
+ * @example
+ * // Empty string
+ * parseSpecShrinkwrap('')
+ * // => { name: null, version: null }
+ */
+export function parseSpecShrinkwrap(spec) {
+  // Handle null/undefined input
+  if (spec == null || typeof spec !== 'string') {
+    return { name: null, version: null };
+  }
+
+  // Skip special protocols
+  if (spec.startsWith('link:') || spec.startsWith('file:')) {
+    return { name: null, version: null };
+  }
+
+  // Remove leading slash if present
+  const cleaned = spec.startsWith('/') ? spec.slice(1) : spec;
+
+  // Handle empty string after removing slash
+  if (!cleaned) {
+    return { name: null, version: null };
+  }
+
+  // Split by slash
+  const parts = cleaned.split('/');
+
+  // Determine if this is a scoped package
+  // Scoped packages start with @ and have format: @scope/name/version[/peer-suffix]
+  // Unscoped packages have format: name/version[/peer-suffix]
+
+  if (cleaned.startsWith('@')) {
+    // Scoped package: @scope/name/version[/peer-suffix]
+    // parts[0] = '@scope', parts[1] = 'name', parts[2] = 'version', parts[3+] = peer suffix
+
+    if (parts.length < 3) {
+      // Not enough parts for scoped package
+      return { name: null, version: null };
+    }
+
+    const scope = parts[0]; // e.g., '@babel'
+    const pkgName = parts[1]; // e.g., 'core'
+    const version = parts[2]; // e.g., '7.23.0'
+
+    // Validate scope format
+    if (!scope.startsWith('@') || !scope.slice(1)) {
+      return { name: null, version: null };
+    }
+
+    // Validate we have both name and version
+    if (!pkgName || !version) {
+      return { name: null, version: null };
+    }
+
+    // The version might contain additional peer suffix parts that got split
+    // In shrinkwrap v3/v4, peer suffixes come after another slash
+    // But the version itself should be the semver string
+
+    return {
+      name: `${scope}/${pkgName}`,
+      version: version
+    };
+  }
+
+  // Unscoped package: name/version[/peer-suffix]
+  // parts[0] = 'name', parts[1] = 'version', parts[2+] = peer suffix
+
+  if (parts.length < 2) {
+    // Not enough parts
+    return { name: null, version: null };
+  }
+
+  const name = parts[0];
+  const version = parts[1];
+
+  // Validate we have both name and version
+  if (!name || !version) {
+    return { name: null, version: null };
+  }
+
+  return { name, version };
+}
+
+/**
+ * Check if a spec has peer dependency suffix (shrinkwrap v3/v4 format).
+ *
+ * In shrinkwrap v3/v4, peer dependencies are appended after the version
+ * with another slash: /name/version/peer@ver+peer2@ver
+ *
+ * @param {string} spec - Package spec from shrinkwrap.yaml
+ * @returns {boolean} True if the spec has peer dependency suffix
+ *
+ * @example
+ * hasPeerSuffix('/lodash/4.17.21') // => false
+ * hasPeerSuffix('/foo/1.0.0/bar@2.0.0') // => true
+ * hasPeerSuffix('/@babel/core/7.23.0') // => false
+ * hasPeerSuffix('/@emotion/styled/10.0.27/react@17.0.2') // => true
+ */
+export function hasPeerSuffix(spec) {
+  if (spec == null || typeof spec !== 'string') {
+    return false;
+  }
+
+  // Remove leading slash
+  const cleaned = spec.startsWith('/') ? spec.slice(1) : spec;
+
+  // Count slashes
+  const slashCount = (cleaned.match(/\//g) || []).length;
+
+  // Scoped packages have 2+ slashes (scope/name/version), peer adds more
+  // Unscoped packages have 1+ slash (name/version), peer adds more
+
+  if (cleaned.startsWith('@')) {
+    // Scoped: needs > 2 slashes for peer suffix
+    return slashCount > 2;
+  }
+
+  // Unscoped: needs > 1 slash for peer suffix
+  return slashCount > 1;
+}
+
+/**
+ * Extract the peer dependency suffix from a shrinkwrap spec.
+ *
+ * @param {string} spec - Package spec from shrinkwrap.yaml
+ * @returns {string|null} The peer suffix or null if none
+ *
+ * @example
+ * extractPeerSuffix('/lodash/4.17.21') // => null
+ * extractPeerSuffix('/foo/1.0.0/bar@2.0.0') // => 'bar@2.0.0'
+ * extractPeerSuffix('/foo/1.0.0/bar@2.0.0+@scope!qar@3.0.0') // => 'bar@2.0.0+@scope!qar@3.0.0'
+ */
+export function extractPeerSuffix(spec) {
+  if (spec == null || typeof spec !== 'string') {
+    return null;
+  }
+
+  // Remove leading slash
+  const cleaned = spec.startsWith('/') ? spec.slice(1) : spec;
+  const parts = cleaned.split('/');
+
+  if (cleaned.startsWith('@')) {
+    // Scoped: @scope/name/version[/peer-suffix...]
+    if (parts.length <= 3) {
+      return null;
+    }
+    return parts.slice(3).join('/');
+  }
+
+  // Unscoped: name/version[/peer-suffix...]
+  if (parts.length <= 2) {
+    return null;
+  }
+  return parts.slice(2).join('/');
+}