flatlock 1.1.0 → 1.3.0

package/src/parsers/yarn-berry.js

@@ -1,39 +1,190 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { parseSyml } from '@yarnpkg/parsers';
 
+/** @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]
  */
 
 /**
- * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
- * !! WARNING: DO NOT MODIFY THIS FUNCTION                                   !!
- * !! AI AGENTS (Claude, Copilot, etc.): DO NOT TOUCH THIS CODE              !!
- * !!                                                                        !!
- * !! This is YARN BERRY LOCKFILE KEY parsing, NOT npm spec parsing.         !!
- * !! Yarn berry lockfile keys have their own format:                        !!
- * !!   - Protocol markers: @npm:, @workspace:, @patch:, @portal:, @link:    !!
- * !!   - Nested protocols: @patch:pkg@npm:version#hash                      !!
- * !!   - Multiple comma-separated entries                                   !!
- * !!                                                                        !!
- * !! npm-package-arg (npa) does NOT understand these formats.               !!
- * !! Do not "improve" this with npa.                                        !!
- * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
- *
- * Extract package name from yarn berry key.
- *
- * Examples:
- *   "lodash@npm:^4.17.21" → "lodash"
- *   "@babel/core@npm:^7.0.0" → "@babel/core"
- *   "@babel/core@npm:^7.0.0, @babel/core@npm:^7.12.3" → "@babel/core"
- *   "@ngageoint/simple-features-js@patch:@ngageoint/simple-features-js@npm:1.1.0#..." → "@ngageoint/simple-features-js"
+ * Extract package name from yarn berry resolution field.
+ *
+ * The resolution field is the CANONICAL identifier and should be used instead of the key.
+ * Keys can contain npm aliases (e.g., "string-width-cjs@npm:string-width@^4.2.0") while
+ * the resolution always contains the actual package name (e.g., "string-width@npm:4.2.3").
+ *
+ * @param {string} resolution - Resolution field from lockfile entry
+ * @returns {string | null} Package name or null if parsing fails
+ *
+ * @example
+ * // Unscoped npm package
+ * parseResolution('lodash@npm:4.17.21')
+ * // => 'lodash'
+ *
+ * @example
+ * // Scoped npm package
+ * parseResolution('@babel/core@npm:7.24.0')
+ * // => '@babel/core'
+ *
+ * @example
+ * // Aliased package - resolution shows the REAL package name
+ * // (key was "string-width-cjs@npm:string-width@^4.2.0")
+ * parseResolution('string-width@npm:4.2.3')
+ * // => 'string-width'
+ *
+ * @example
+ * // Scoped aliased package - resolution shows the REAL package name
+ * // (key was "@babel-baseline/core@npm:@babel/core@7.24.4")
+ * parseResolution('@babel/core@npm:7.24.4')
+ * // => '@babel/core'
+ *
+ * @example
+ * // Patch protocol (nested protocols)
+ * parseResolution('pkg@patch:pkg@npm:1.0.0#./patch')
+ * // => 'pkg'
+ *
+ * @example
+ * // Scoped package with patch protocol
+ * parseResolution('@scope/pkg@patch:@scope/pkg@npm:1.0.0#./fix.patch')
+ * // => '@scope/pkg'
+ *
+ * @example
+ * // Workspace protocol
+ * parseResolution('my-pkg@workspace:packages/my-pkg')
+ * // => 'my-pkg'
+ *
+ * @example
+ * // Scoped workspace package
+ * parseResolution('@myorg/utils@workspace:packages/utils')
+ * // => '@myorg/utils'
+ *
+ * @example
+ * // Git protocol
+ * parseResolution('my-lib@git:github.com/user/repo#commit-hash')
+ * // => 'my-lib'
+ *
+ * @example
+ * // Null/empty input
+ * parseResolution(null)
+ * // => null
+ *
+ * @example
+ * // Empty string
+ * parseResolution('')
+ * // => null
+ *
+ * @example
+ * // Portal protocol (symlink to external package)
+ * parseResolution('@scope/external@portal:../external-pkg')
+ * // => '@scope/external'
+ */
+export function parseResolution(resolution) {
+  if (!resolution) return null;
+
+  // Resolution format: name@protocol:version or @scope/name@protocol:version
+  // Examples:
+  //   "lodash@npm:4.17.21"
+  //   "@babel/core@npm:7.24.0"
+  //   "pkg@patch:pkg@npm:1.0.0#./patch"
+
+  // Handle scoped packages: @scope/name@protocol:version
+  if (resolution.startsWith('@')) {
+    const slashIndex = resolution.indexOf('/');
+    if (slashIndex !== -1) {
+      // Find the @ after the scope/name
+      const afterSlash = resolution.indexOf('@', slashIndex);
+      if (afterSlash !== -1) {
+        return resolution.slice(0, afterSlash);
+      }
+    }
+  }
+
+  // Handle unscoped packages: name@protocol:version
+  const atIndex = resolution.indexOf('@');
+  if (atIndex !== -1) {
+    return resolution.slice(0, atIndex);
+  }
+
+  return null;
+}
+
+/**
+ * Extract package name from yarn berry key (fallback for when resolution is unavailable).
+ *
+ * WARNING: Keys can contain npm aliases. Prefer parseResolution() when possible.
+ * The key may return an alias name instead of the real package name.
  *
  * @param {string} key - Lockfile entry key
- * @returns {string} Package name
+ * @returns {string} Package name (may be alias name, not canonical name)
+ *
+ * @example
+ * // Simple unscoped package
+ * parseLockfileKey('lodash@npm:^4.17.21')
+ * // => 'lodash'
+ *
+ * @example
+ * // Scoped package
+ * parseLockfileKey('@babel/core@npm:^7.24.0')
+ * // => '@babel/core'
+ *
+ * @example
+ * // Multiple version ranges (comma-separated) - takes first entry
+ * parseLockfileKey('@types/node@npm:^18.0.0, @types/node@npm:^20.0.0')
+ * // => '@types/node'
+ *
+ * @example
+ * // npm alias - returns the ALIAS name (not real package)
+ * // Use parseResolution() for the real package name
+ * parseLockfileKey('string-width-cjs@npm:string-width@^4.2.0')
+ * // => 'string-width-cjs'
+ *
+ * @example
+ * // Scoped npm alias
+ * parseLockfileKey('@babel-baseline/core@npm:@babel/core@7.24.4')
+ * // => '@babel-baseline/core'
+ *
+ * @example
+ * // Workspace protocol
+ * parseLockfileKey('my-pkg@workspace:packages/my-pkg')
+ * // => 'my-pkg'
+ *
+ * @example
+ * // Scoped workspace package
+ * parseLockfileKey('@myorg/utils@workspace:.')
+ * // => '@myorg/utils'
+ *
+ * @example
+ * // Portal protocol
+ * parseLockfileKey('external-pkg@portal:../some/path')
+ * // => 'external-pkg'
+ *
+ * @example
+ * // Link protocol
+ * parseLockfileKey('linked-pkg@link:./local')
+ * // => 'linked-pkg'
+ *
+ * @example
+ * // Patch protocol (complex nested format)
+ * parseLockfileKey('pkg@patch:pkg@npm:1.0.0#./patches/fix.patch')
+ * // => 'pkg'
+ *
+ * @example
+ * // Scoped patch
+ * parseLockfileKey('@scope/pkg@patch:@scope/pkg@npm:1.0.0#./fix.patch')
+ * // => '@scope/pkg'
+ *
+ * @example
+ * // File protocol
+ * parseLockfileKey('local-pkg@file:../local-package')
+ * // => 'local-pkg'
  */
 export function parseLockfileKey(key) {
   // Keys can have multiple comma-separated entries, take the first one
@@ -73,29 +224,37 @@ export function parseLockfileKey(key) {
 
 /**
  * Parse yarn.lock v2+ (berry)
- * @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* fromYarnBerryLock(content, _options = {}) {
-  const lockfile = parseSyml(content);
+export function* fromYarnBerryLock(input, _options = {}) {
+  const lockfile = typeof input === 'string' ? parseSyml(input) : input;
 
   for (const [key, pkg] of Object.entries(lockfile)) {
     // Skip metadata
     if (key === '__metadata') continue;
 
-    const name = parseLockfileKey(key);
     const { version, checksum, resolution } = pkg;
 
-    // Check if this is a link (workspace:, portal:, or link: protocol)
+    // Check if this is a local/workspace entry (workspace:, portal:, or link: protocol)
+    // The protocol appears after @ in both key and resolution: "pkg@workspace:..."
     const link =
-      resolution?.startsWith('workspace:') ||
-      resolution?.startsWith('portal:') ||
-      resolution?.startsWith('link:');
+      key.includes('@workspace:') ||
+      key.includes('@portal:') ||
+      key.includes('@link:') ||
+      resolution?.includes('@workspace:') ||
+      resolution?.includes('@portal:') ||
+      resolution?.includes('@link:');
 
     // Skip workspace/link entries - flatlock only cares about external dependencies
     if (link) continue;
 
+    // Use the resolution field for the package name - it's the canonical identifier
+    // Keys can contain npm aliases (e.g., "string-width-cjs@npm:string-width@^4.2.0")
+    // but resolution always has the actual package name (e.g., "string-width@npm:4.2.3")
+    const name = parseResolution(resolution) || parseLockfileKey(key);
+
     if (name && version) {
       /** @type {Dependency} */
       const dep = { name, version };
@@ -105,3 +264,79 @@ export function* fromYarnBerryLock(content, _options = {}) {
     }
   }
 }
+
+/**
+ * Extract workspace paths from yarn berry lockfile.
+ *
+ * Yarn berry workspace entries use `@workspace:` protocol in keys.
+ * Keys can have multiple comma-separated descriptors.
+ *
+ * @param {string | object} input - Lockfile content string or pre-parsed object
+ * @returns {string[]} Array of workspace paths (e.g., ['packages/foo', 'packages/bar'])
+ *
+ * @example
+ * extractWorkspacePaths(lockfile)
+ * // => ['packages/babel-core', 'packages/babel-parser', ...]
+ */
+export function extractWorkspacePaths(input) {
+  const lockfile = typeof input === 'string' ? parseSyml(input) : input;
+  const paths = new Set();
+
+  for (const key of Object.keys(lockfile)) {
+    if (key === '__metadata') continue;
+    if (!key.includes('@workspace:')) continue;
+
+    // Keys can have multiple comma-separated descriptors:
+    // "@babel/types@workspace:*, @babel/types@workspace:^, @babel/types@workspace:packages/babel-types"
+    const descriptors = key.split(', ');
+    for (const desc of descriptors) {
+      if (!desc.includes('@workspace:')) continue;
+
+      const wsIndex = desc.indexOf('@workspace:');
+      const path = desc.slice(wsIndex + '@workspace:'.length);
+
+      // Skip wildcards (*, ^) and root workspace (.)
+      if (path && path !== '.' && path !== '*' && path !== '^' && path.includes('/')) {
+        paths.add(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');
+ * // => { 'packages/foo': { name: '@scope/foo', 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/yarn-classic.js

@@ -1,16 +1,19 @@
 import yarnLockfile from '@yarnpkg/lockfile';
 
-const { parse } = yarnLockfile;
+/** @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} YarnClassicParseResult
+ * @property {'success' | 'merge' | 'conflict'} type - Parse result type
+ * @property {Record<string, any>} object - Parsed lockfile object
  */
 
+/**
+ * The yarn classic parse function (handles CJS/ESM interop)
+ * @type {(content: string) => YarnClassicParseResult}
+ */
+export const parseYarnClassic = yarnLockfile.default?.parse || yarnLockfile.parse;
+
 /**
  * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  * !! WARNING: DO NOT MODIFY THIS FUNCTION                                   !!
@@ -27,14 +30,68 @@ const { parse } = yarnLockfile;
  *
  * Extract package name from yarn classic key.
  *
- * Examples:
- *   "lodash@^4.17.21" → "lodash"
- *   "@babel/core@^7.0.0" → "@babel/core"
- *   "lodash@^4.17.21, lodash@^4.0.0" → "lodash" (multiple version ranges)
- *   "@babel/traverse--for-generate-function-map@npm:@babel/traverse@^7.25.3" → "@babel/traverse--for-generate-function-map"
- *
  * @param {string} key - Lockfile entry key
  * @returns {string} Package name
+ *
+ * @example
+ * // Simple unscoped package with semver range
+ * parseLockfileKey('lodash@^4.17.21')
+ * // => 'lodash'
+ *
+ * @example
+ * // Scoped package
+ * parseLockfileKey('@babel/core@^7.0.0')
+ * // => '@babel/core'
+ *
+ * @example
+ * // Multiple version ranges (comma-separated) - takes first entry
+ * parseLockfileKey('lodash@^4.17.21, lodash@^4.0.0')
+ * // => 'lodash'
+ *
+ * @example
+ * // Multiple ranges for scoped package
+ * parseLockfileKey('@types/node@^18.0.0, @types/node@^20.0.0')
+ * // => '@types/node'
+ *
+ * @example
+ * // npm: alias protocol - returns the ALIAS name
+ * parseLockfileKey('@babel/traverse--for-generate-function-map@npm:@babel/traverse@^7.25.3')
+ * // => '@babel/traverse--for-generate-function-map'
+ *
+ * @example
+ * // Unscoped alias
+ * parseLockfileKey('string-width-cjs@npm:string-width@^4.2.0')
+ * // => 'string-width-cjs'
+ *
+ * @example
+ * // Exact version
+ * parseLockfileKey('typescript@5.3.3')
+ * // => 'typescript'
+ *
+ * @example
+ * // Git URL specifier
+ * parseLockfileKey('my-lib@github:user/repo#v1.0.0')
+ * // => 'my-lib'
+ *
+ * @example
+ * // Tarball URL
+ * parseLockfileKey('custom-pkg@https://example.com/pkg.tgz')
+ * // => 'custom-pkg'
+ *
+ * @example
+ * // Package with prerelease version
+ * parseLockfileKey('@next/env@^14.0.0-canary.0')
+ * // => '@next/env'
+ *
+ * @example
+ * // Package without @ (bare name, edge case)
+ * parseLockfileKey('lodash')
+ * // => 'lodash'
+ *
+ * @example
+ * // Deeply scoped alias pointing to scoped package
+ * parseLockfileKey('@myorg/my-alias@npm:@original/package@^1.0.0')
+ * // => '@myorg/my-alias'
  */
 export function parseLockfileKey(key) {
   // Keys can have multiple version ranges: "pkg@^1.0.0, pkg@^2.0.0"
@@ -72,19 +129,22 @@ export function parseLockfileKey(key) {
 
 /**
  * Parse yarn.lock v1 (classic)
- * @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* fromYarnClassicLock(content, _options = {}) {
-  const parsed = parse(content);
-
-  if (parsed.type !== 'success') {
-    throw new Error(`Failed to parse yarn.lock: ${parsed.type}`);
+export function* fromYarnClassicLock(input, _options = {}) {
+  let lockfile;
+  if (typeof input === 'string') {
+    const result = parseYarnClassic(input);
+    if (result.type !== 'success' && result.type !== 'merge') {
+      throw new Error('Failed to parse yarn.lock');
+    }
+    lockfile = result.object;
+  } else {
+    lockfile = input;
   }
 
-  const lockfile = parsed.object;
-
   for (const [key, pkg] of Object.entries(lockfile)) {
     const name = parseLockfileKey(key);
     const { version, integrity, resolved } = pkg;