flatlock 1.1.0 → 1.2.0

package/src/parsers/npm.js

@@ -1,11 +1,4 @@
-/**
- * @typedef {Object} Dependency
- * @property {string} name - Package name
- * @property {string} version - Resolved version
- * @property {string} [integrity] - Integrity hash
- * @property {string} [resolved] - Resolution URL
- * @property {boolean} [link] - True if this is a symlink
- */
+/** @typedef {import('./types.js').Dependency} Dependency */
 
 /**
  * LIMITATION: Workspace symlinks are not yielded
@@ -43,13 +36,68 @@
  *   pkg := name (unscoped)
  *     | @scope/name (scoped)
  *
- * Examples:
- *   - node_modules/lodash → "lodash"
- *   - node_modules/@babel/core → "@babel/core"
- *   - node_modules/foo/node_modules/@scope/bar → "@scope/bar"
- *
  * @param {string} path - Lockfile path key
  * @returns {string} Package name
+ *
+ * @example
+ * // Simple unscoped package
+ * parseLockfileKey('node_modules/lodash')
+ * // => 'lodash'
+ *
+ * @example
+ * // Scoped package
+ * parseLockfileKey('node_modules/@babel/core')
+ * // => '@babel/core'
+ *
+ * @example
+ * // Nested dependency (hoisted conflict resolution)
+ * parseLockfileKey('node_modules/foo/node_modules/bar')
+ * // => 'bar'
+ *
+ * @example
+ * // Nested scoped dependency
+ * parseLockfileKey('node_modules/foo/node_modules/@scope/bar')
+ * // => '@scope/bar'
+ *
+ * @example
+ * // Deeply nested dependency
+ * parseLockfileKey('node_modules/a/node_modules/b/node_modules/c')
+ * // => 'c'
+ *
+ * @example
+ * // Deeply nested scoped dependency
+ * parseLockfileKey('node_modules/a/node_modules/@types/node')
+ * // => '@types/node'
+ *
+ * @example
+ * // Workspace package path (definition)
+ * parseLockfileKey('packages/my-lib')
+ * // => 'my-lib'
+ *
+ * @example
+ * // Workspace nested dependency
+ * parseLockfileKey('packages/my-lib/node_modules/lodash')
+ * // => 'lodash'
+ *
+ * @example
+ * // Workspace nested scoped dependency
+ * parseLockfileKey('packages/my-lib/node_modules/@types/react')
+ * // => '@types/react'
+ *
+ * @example
+ * // Package with hyphenated name
+ * parseLockfileKey('node_modules/string-width')
+ * // => 'string-width'
+ *
+ * @example
+ * // Scoped package with hyphenated name
+ * parseLockfileKey('node_modules/@emotion/styled')
+ * // => '@emotion/styled'
+ *
+ * @example
+ * // Complex nested path
+ * parseLockfileKey('node_modules/@babel/core/node_modules/@babel/helper-compilation-targets')
+ * // => '@babel/helper-compilation-targets'
  */
 export function parseLockfileKey(path) {
   const parts = path.split('/');
@@ -61,12 +109,12 @@ export function parseLockfileKey(path) {
 
 /**
  * Parse npm package-lock.json (v1, v2, v3)
- * @param {string} content - Lockfile content
+ * @param {string | object} input - Lockfile content string or pre-parsed object
  * @param {Object} [_options] - Parser options (unused, reserved for future use)
  * @returns {Generator<Dependency>}
  */
-export function* fromPackageLock(content, _options = {}) {
-  const lockfile = JSON.parse(content);
+export function* fromPackageLock(input, _options = {}) {
+  const lockfile = typeof input === 'string' ? JSON.parse(input) : input;
   const packages = lockfile.packages || {};
 
   for (const [path, pkg] of Object.entries(packages)) {

package/src/parsers/pnpm/detect.js

@@ -0,0 +1,198 @@
+/**
+ * @fileoverview Version detection for pnpm lockfiles
+ *
+ * Detects the era and version of pnpm lockfiles including:
+ * - shrinkwrap.yaml (v3/v4) from 2016-2019
+ * - pnpm-lock.yaml v5.x (2019-2022)
+ * - pnpm-lock.yaml v6.0 (2023)
+ * - pnpm-lock.yaml v9.0 (2024+)
+ *
+ * @module flatlock/parsers/pnpm/detect
+ */
+
+/**
+ * @typedef {'shrinkwrap'|'v5'|'v5-inline'|'v6'|'v9'|'unknown'} LockfileEra
+ */
+
+/**
+ * @typedef {Object} DetectedVersion
+ * @property {LockfileEra} era - The lockfile era/format family
+ * @property {string|number} version - The raw version from the lockfile
+ * @property {boolean} isShrinkwrap - True if this is a shrinkwrap.yaml file
+ */
+
+/**
+ * Detect the version and era of a pnpm lockfile.
+ *
+ * Version detection rules:
+ * - If `shrinkwrapVersion` exists: shrinkwrap era (v3/v4)
+ * - If `lockfileVersion` is a number: v5 era
+ * - If `lockfileVersion` is '5.4-inlineSpecifiers': v5-inline era
+ * - If `lockfileVersion` starts with '6': v6 era
+ * - If `lockfileVersion` starts with '9': v9 era
+ *
+ * @param {Object} lockfile - Parsed pnpm lockfile object
+ * @param {string|number} [lockfile.lockfileVersion] - The lockfile version field
+ * @param {number} [lockfile.shrinkwrapVersion] - The shrinkwrap version field (v3/v4)
+ * @param {number} [lockfile.shrinkwrapMinorVersion] - Minor version for shrinkwrap
+ * @returns {DetectedVersion} The detected version information
+ *
+ * @example
+ * // shrinkwrap.yaml v3
+ * detectVersion({ shrinkwrapVersion: 3 })
+ * // => { era: 'shrinkwrap', version: 3, isShrinkwrap: true }
+ *
+ * @example
+ * // pnpm-lock.yaml v5.4
+ * detectVersion({ lockfileVersion: 5.4 })
+ * // => { era: 'v5', version: 5.4, isShrinkwrap: false }
+ *
+ * @example
+ * // pnpm-lock.yaml v6.0
+ * detectVersion({ lockfileVersion: '6.0' })
+ * // => { era: 'v6', version: '6.0', isShrinkwrap: false }
+ *
+ * @example
+ * // pnpm-lock.yaml v9.0
+ * detectVersion({ lockfileVersion: '9.0' })
+ * // => { era: 'v9', version: '9.0', isShrinkwrap: false }
+ */
+export function detectVersion(lockfile) {
+  // Handle null/undefined input
+  if (!lockfile || typeof lockfile !== 'object') {
+    return { era: 'unknown', version: '', isShrinkwrap: false };
+  }
+
+  // Check for shrinkwrap.yaml (v3/v4) - oldest format
+  if ('shrinkwrapVersion' in lockfile) {
+    const version = lockfile.shrinkwrapVersion;
+    return {
+      era: 'shrinkwrap',
+      version: version ?? 0,
+      isShrinkwrap: true
+    };
+  }
+
+  // Get the lockfileVersion
+  const version = lockfile.lockfileVersion;
+
+  // Handle missing version
+  if (version === undefined || version === null) {
+    return { era: 'unknown', version: '', isShrinkwrap: false };
+  }
+
+  // Numeric version: v5.x era
+  if (typeof version === 'number') {
+    return {
+      era: 'v5',
+      version: version,
+      isShrinkwrap: false
+    };
+  }
+
+  // String version
+  if (typeof version === 'string') {
+    // v5.4-inlineSpecifiers: experimental transitional format
+    if (version.includes('inlineSpecifiers')) {
+      return {
+        era: 'v5-inline',
+        version: version,
+        isShrinkwrap: false
+      };
+    }
+
+    // v9.x era (2024+)
+    if (version.startsWith('9')) {
+      return {
+        era: 'v9',
+        version: version,
+        isShrinkwrap: false
+      };
+    }
+
+    // v6.x era (2023)
+    if (version.startsWith('6')) {
+      return {
+        era: 'v6',
+        version: version,
+        isShrinkwrap: false
+      };
+    }
+
+    // v7.x or v8.x would fall here if they existed (they don't)
+    // Could be a future version we don't know about
+  }
+
+  return { era: 'unknown', version: version, isShrinkwrap: false };
+}
+
+/**
+ * Check if a lockfile uses the v6+ package key format (name@version).
+ *
+ * v5 and earlier use: /name/version or /@scope/name/version
+ * v6+ use: /name@version or /@scope/name@version
+ * v9+ use: name@version (no leading slash)
+ *
+ * @param {DetectedVersion} detected - The detected version info
+ * @returns {boolean} True if the lockfile uses @ separator for name@version
+ *
+ * @example
+ * usesAtSeparator({ era: 'v5', version: 5.4 }) // => false
+ * usesAtSeparator({ era: 'v6', version: '6.0' }) // => true
+ * usesAtSeparator({ era: 'v9', version: '9.0' }) // => true
+ */
+export function usesAtSeparator(detected) {
+  return detected.era === 'v6' || detected.era === 'v9';
+}
+
+/**
+ * Check if a lockfile uses the packages/snapshots split (v9+).
+ *
+ * v9 separates package metadata (packages) from dependency relationships (snapshots).
+ *
+ * @param {DetectedVersion} detected - The detected version info
+ * @returns {boolean} True if the lockfile has packages/snapshots split
+ *
+ * @example
+ * usesSnapshotsSplit({ era: 'v6', version: '6.0' }) // => false
+ * usesSnapshotsSplit({ era: 'v9', version: '9.0' }) // => true
+ */
+export function usesSnapshotsSplit(detected) {
+  return detected.era === 'v9';
+}
+
+/**
+ * Check if a lockfile uses inline specifiers.
+ *
+ * v5.4-inlineSpecifiers and v6+ use inline specifiers in importers.
+ * Earlier versions have a separate `specifiers` block.
+ *
+ * @param {DetectedVersion} detected - The detected version info
+ * @returns {boolean} True if specifiers are inlined
+ *
+ * @example
+ * usesInlineSpecifiers({ era: 'v5', version: 5.4 }) // => false
+ * usesInlineSpecifiers({ era: 'v5-inline', version: '5.4-inlineSpecifiers' }) // => true
+ * usesInlineSpecifiers({ era: 'v6', version: '6.0' }) // => true
+ */
+export function usesInlineSpecifiers(detected) {
+  return detected.era === 'v5-inline' || detected.era === 'v6' || detected.era === 'v9';
+}
+
+/**
+ * Check if package keys have a leading slash.
+ *
+ * v5 and v6 use leading slash: /name/version or /name@version
+ * v9 omits leading slash: name@version
+ *
+ * @param {DetectedVersion} detected - The detected version info
+ * @returns {boolean} True if package keys have leading slash
+ *
+ * @example
+ * hasLeadingSlash({ era: 'v5', version: 5.4 }) // => true
+ * hasLeadingSlash({ era: 'v6', version: '6.0' }) // => true
+ * hasLeadingSlash({ era: 'v9', version: '9.0' }) // => false
+ */
+export function hasLeadingSlash(detected) {
+  return detected.era !== 'v9';
+}

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';