flatlock 1.1.0 → 1.3.0

package/src/parsers/npm.js

@@ -1,10 +1,16 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** @typedef {import('./types.js').Dependency} Dependency */
+
 /**
- * @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 {Object} WorkspacePackage
+ * @property {string} name
+ * @property {string} version
+ * @property {Record<string, string>} [dependencies]
+ * @property {Record<string, string>} [devDependencies]
+ * @property {Record<string, string>} [optionalDependencies]
+ * @property {Record<string, string>} [peerDependencies]
  */
 
 /**
@@ -43,13 +49,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 +122,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)) {
@@ -93,3 +154,72 @@ export function* fromPackageLock(content, _options = {}) {
     }
   }
 }
+
+/**
+ * Extract workspace paths from npm lockfile.
+ *
+ * npm workspace packages are entries in `packages` that:
+ * - Are not the root ('')
+ * - Don't contain 'node_modules/' (those are installed deps)
+ * - Have a version field
+ *
+ * @param {string | object} input - Lockfile content string or pre-parsed object
+ * @returns {string[]} Array of workspace paths (e.g., ['workspaces/arborist', 'workspaces/libnpmfund'])
+ *
+ * @example
+ * extractWorkspacePaths(lockfile)
+ * // => ['workspaces/arborist', 'workspaces/libnpmfund', ...]
+ */
+export function extractWorkspacePaths(input) {
+  const lockfile = typeof input === 'string' ? JSON.parse(input) : input;
+  const packages = lockfile.packages || {};
+  const paths = [];
+
+  for (const [path, pkg] of Object.entries(packages)) {
+    // Skip root and node_modules entries
+    if (path === '' || path.includes('node_modules')) continue;
+
+    // Workspace entries have a version
+    if (pkg.version) {
+      paths.push(path);
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Build workspace packages map by reading package.json files.
+ *
+ * @param {string | object} input - Lockfile content string or pre-parsed object
+ * @param {string} repoDir - Path to repository root
+ * @returns {Promise<Record<string, WorkspacePackage>>} Map of workspace path to package info
+ *
+ * @example
+ * const workspaces = await buildWorkspacePackages(lockfile, '/path/to/repo');
+ * // => { 'workspaces/arborist': { name: '@npmcli/arborist', version: '1.0.0', dependencies: {...} } }
+ */
+export async function buildWorkspacePackages(input, repoDir) {
+  const paths = extractWorkspacePaths(input);
+  /** @type {Record<string, WorkspacePackage>} */
+  const workspacePackages = {};
+
+  for (const wsPath of paths) {
+    const pkgJsonPath = join(repoDir, wsPath, 'package.json');
+    try {
+      const pkg = JSON.parse(await readFile(pkgJsonPath, 'utf8'));
+      workspacePackages[wsPath] = {
+        name: pkg.name,
+        version: pkg.version || '0.0.0',
+        dependencies: pkg.dependencies,
+        devDependencies: pkg.devDependencies,
+        optionalDependencies: pkg.optionalDependencies,
+        peerDependencies: pkg.peerDependencies
+      };
+    } catch {
+      // Skip workspaces with missing or invalid package.json
+    }
+  }
+
+  return workspacePackages;
+}

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