flatlock 1.0.1 → 1.2.0

package/src/index.js

@@ -1,17 +1,21 @@
 import { readFile } from 'node:fs/promises';
-import { Type, detectType } from './detect.js';
-import { Ok, Err } from './result.js';
+import { detectType, Type } from './detect.js';
 import {
   fromPackageLock,
   fromPnpmLock,
-  fromYarnClassicLock,
-  fromYarnBerryLock
+  fromYarnBerryLock,
+  fromYarnClassicLock
 } from './parsers/index.js';
+import { Err, Ok } from './result.js';
+import { FlatlockSet } from './set.js';
+
+/** @typedef {import('./detect.js').LockfileType} LockfileType */
+/** @typedef {import('./parsers/npm.js').Dependency} Dependency */
 
 /**
- * @typedef {import('./detect.js').LockfileType} LockfileType
- * @typedef {import('./result.js').Result} Result
- * @typedef {import('./parsers/npm.js').Dependency} Dependency
+ * @typedef {Object} ParseOptions
+ * @property {string} [path] - Path hint for type detection
+ * @property {LockfileType} [type] - Explicit type (skip detection)
  */
 
 // Re-export Type and detection
@@ -23,6 +27,9 @@ export { Ok, Err };
 // Re-export individual parsers
 export { fromPackageLock, fromPnpmLock, fromYarnClassicLock, fromYarnBerryLock };
 
+// Re-export FlatlockSet class
+export { FlatlockSet };
+
 /**
  * Parse lockfile from path (auto-detect type)
  * @param {string} path - Path to lockfile
@@ -73,23 +80,23 @@ export function* fromString(content, options = {}) {
 /**
  * Try to parse lockfile from path (returns Result)
  * @param {string} path - Path to lockfile
- * @param {Object} [options] - Parser options
- * @returns {Promise<Result<AsyncGenerator<Dependency>>>}
+ * @param {ParseOptions} [options] - Parser options
+ * @returns {Promise<import('./result.js').Result<AsyncGenerator<Dependency>>>}
  */
 export async function tryFromPath(path, options = {}) {
   try {
     const generator = fromPath(path, options);
     return Ok(generator);
   } catch (err) {
-    return Err(err);
+    return Err(/** @type {Error} */ (err));
   }
 }
 
 /**
  * Try to parse lockfile from string (returns Result)
  * @param {string} content - Lockfile content
- * @param {Object} [options] - Parser options
- * @returns {Result<Generator<Dependency>>}
+ * @param {ParseOptions} [options] - Parser options
+ * @returns {import('./result.js').Result<Generator<Dependency>>}
  */
 export function tryFromString(content, options = {}) {
   try {
@@ -98,7 +105,7 @@ export function tryFromString(content, options = {}) {
     const generator = fromString(content, { ...options, type });
     return Ok(generator);
   } catch (err) {
-    return Err(err);
+    return Err(/** @type {Error} */ (err));
   }
 }
 
@@ -127,8 +134,8 @@ export function* fromYarnLock(content, options = {}) {
 export async function collect(pathOrContent, options = {}) {
   const deps = [];
 
-  // Check if it's a path or content
-  const isPath = !pathOrContent.includes('\n') && !pathOrContent.startsWith('{');
+  // Better heuristic: paths don't contain newlines and are reasonably short
+  const isPath = !pathOrContent.includes('\n') && pathOrContent.length < 1000;
 
   if (isPath) {
     for await (const dep of fromPath(pathOrContent, options)) {
@@ -142,3 +149,14 @@ export async function collect(pathOrContent, options = {}) {
 
   return deps;
 }
+
+// Re-export compare API
+export { compare, compareAll, getAvailableParsers } from './compare.js';
+
+// Re-export lockfile key parsing utilities
+export {
+  parseNpmKey,
+  parsePnpmKey,
+  parseYarnBerryKey,
+  parseYarnClassicKey
+} from './parsers/index.js';

package/src/parsers/index.js

@@ -2,7 +2,15 @@
  * Re-export all lockfile parsers
  */
 
-export { fromPackageLock } from './npm.js';
-export { fromPnpmLock } from './pnpm.js';
-export { fromYarnClassicLock } from './yarn-classic.js';
-export { fromYarnBerryLock } from './yarn-berry.js';
+export { fromPackageLock, parseLockfileKey as parseNpmKey } from './npm.js';
+export { fromPnpmLock, parseLockfileKey as parsePnpmKey } from './pnpm.js';
+export {
+  fromYarnBerryLock,
+  parseLockfileKey as parseYarnBerryKey,
+  parseResolution as parseYarnBerryResolution
+} from './yarn-berry.js';
+export {
+  fromYarnClassicLock,
+  parseLockfileKey as parseYarnClassicKey,
+  parseYarnClassic
+} from './yarn-classic.js';

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,32 +36,85 @@
  *   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'
  */
-function extractPackageName(path) {
+export function parseLockfileKey(path) {
   const parts = path.split('/');
-  const name = parts.at(-1);
+  const name = /** @type {string} */ (parts.at(-1));
   const maybeScope = parts.at(-2);
 
-  return maybeScope?.startsWith('@')
-    ? `${maybeScope}/${name}`
-    : name;
+  return maybeScope?.startsWith('@') ? `${maybeScope}/${name}` : name;
 }
 
 /**
  * Parse npm package-lock.json (v1, v2, v3)
- * @param {string} content - Lockfile content
- * @param {Object} [options] - Parser options
+ * @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)) {
@@ -81,11 +127,12 @@ export function* fromPackageLock(content, _options = {}) {
     //   2. node_modules/<workspace-package.json-name> → link, NO version (symlink)
     if (!path.includes('node_modules/')) continue;
 
-    const name = extractPackageName(path);
+    const name = parseLockfileKey(path);
     const { version, integrity, resolved, link } = pkg;
 
     // Only yield if we have a name and version
     if (name && version) {
+      /** @type {Dependency} */
       const dep = { name, version };
       if (integrity) dep.integrity = integrity;
       if (resolved) dep.resolved = resolved;

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