flatlock 1.0.1 → 1.1.0

package/README.md

@@ -4,7 +4,7 @@ The Matlock of lockfile parsers - cuts through the complexity to get just the fa
 
 ## What makes `flatlock` different?
 
-![matlockish](https://github.com/indexzero/flatlock/raw/main/doc/matlockish.png)
+![matlockish](https://github.com/indexzero/flatlock/raw/main/doc/img/matlockish.png)
 
 Most lockfile parsers (like `@npmcli/arborist` or `snyk-nodejs-lockfile-parser`) build the full dependency graph with edges representing relationships between packages. This is necessary for dependency resolution but overkill for many use cases.
 

package/bin/flatlock-cmp.js

@@ -1,243 +1,10 @@
 #!/usr/bin/env node
 
-import { readFile, readdir, stat, mkdir, writeFile, rm } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
 import { parseArgs } from 'node:util';
-import { fileURLToPath } from 'node:url';
-import crypto from 'node:crypto';
 import * as flatlock from '../src/index.js';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-// Unique run ID for this script execution (7 char hash of timestamp)
-const RUN_ID = Date.now().toString(36).slice(-7);
-const TMP_BASE = join(__dirname, 'tmp', RUN_ID);
-let tmpDirCreated = false;
-
-// Comparison parsers (lazy loaded)
-let Arborist, yarnLockfile, parseSyml, yaml;
-
-async function loadArborist() {
-  if (!Arborist) {
-    const mod = await import('@npmcli/arborist');
-    Arborist = mod.default;
-  }
-  return Arborist;
-}
-
-async function loadYarnClassic() {
-  if (!yarnLockfile) {
-    const mod = await import('@yarnpkg/lockfile');
-    yarnLockfile = mod.default || mod;
-  }
-  return yarnLockfile;
-}
-
-async function loadYarnBerry() {
-  if (!parseSyml) {
-    const mod = await import('@yarnpkg/parsers');
-    parseSyml = mod.parseSyml;
-  }
-  return parseSyml;
-}
-
-async function loadYaml() {
-  if (!yaml) {
-    const mod = await import('js-yaml');
-    yaml = mod.default;
-  }
-  return yaml;
-}
-
-/**
- * Ensure the temp directory for this run exists
- */
-async function ensureTmpDir() {
-  if (!tmpDirCreated) {
-    await mkdir(TMP_BASE, { recursive: true });
-    tmpDirCreated = true;
-  }
-}
-
-/**
- * Cleanup the temp directory for this run
- */
-async function cleanup() {
-  if (tmpDirCreated) {
-    try {
-      await rm(TMP_BASE, { recursive: true, force: true });
-    } catch {
-      // Ignore cleanup errors
-    }
-  }
-}
-
-/**
- * Get packages set using @npmcli/arborist
- *
- * Arborist requires a directory with package-lock.json (and optionally package.json).
- * We create a temp directory structure for each lockfile:
- *   bin/tmp/<run-id>/<file-hash>/package-lock.json
- */
-async function getPackagesFromNpm(content, filepath) {
-  const ArboristClass = await loadArborist();
-  await ensureTmpDir();
-
-  // Create unique subdir for this lockfile
-  const fileId = crypto.createHash('md5').update(filepath).digest('hex').slice(0, 7);
-  const tmpDir = join(TMP_BASE, fileId);
-
-  await mkdir(tmpDir, { recursive: true });
-  await writeFile(join(tmpDir, 'package-lock.json'), content);
-
-  // Create minimal package.json from lockfile root entry
-  const lockfile = JSON.parse(content);
-  const root = lockfile.packages?.[''] || {};
-  const pkg = {
-    name: root.name || 'arborist-temp',
-    version: root.version || '1.0.0'
-  };
-  await writeFile(join(tmpDir, 'package.json'), JSON.stringify(pkg));
-
-  try {
-    const arb = new ArboristClass({ path: tmpDir });
-    const tree = await arb.loadVirtual();
-
-    const result = new Set();
-    let workspaceCount = 0;
-    for (const node of tree.inventory.values()) {
-      if (node.isRoot) continue;
-      // Skip workspace symlinks (link:true, no version in raw lockfile)
-      if (node.isLink) {
-        workspaceCount++;
-        continue;
-      }
-      // Skip workspace package definitions (not in node_modules)
-      // Flatlock only yields packages from node_modules/ paths
-      if (node.location && !node.location.includes('node_modules')) {
-        workspaceCount++;
-        continue;
-      }
-      if (node.name && node.version) {
-        result.add(`${node.name}@${node.version}`);
-      }
-    }
-    return { packages: result, workspaceCount };
-  } finally {
-    // Cleanup this specific lockfile's temp dir
-    await rm(tmpDir, { recursive: true, force: true });
-  }
-}
-
-/**
- * Get packages set using @yarnpkg/lockfile (classic)
- */
-async function getPackagesFromYarnClassic(content) {
-  const yarnLock = await loadYarnClassic();
-  const parse = yarnLock.parse || yarnLock.default?.parse;
-  const { object: lockfile } = parse(content);
-
-  const result = new Set();
-  let workspaceCount = 0;
-  for (const [key, pkg] of Object.entries(lockfile)) {
-    if (key === '__metadata') continue;
-
-    // Skip workspace/link entries - flatlock only cares about external dependencies
-    const resolved = pkg.resolved || '';
-    if (resolved.startsWith('file:') || resolved.startsWith('link:')) {
-      workspaceCount++;
-      continue;
-    }
-
-    let name;
-    if (key.startsWith('@')) {
-      const idx = key.indexOf('@', 1);
-      name = key.slice(0, idx);
-    } else {
-      name = key.split('@')[0];
-    }
-    if (name && pkg.version) result.add(`${name}@${pkg.version}`);
-  }
-
-  return { packages: result, workspaceCount };
-}
-
-/**
- * Get packages set using @yarnpkg/parsers (berry)
- */
-async function getPackagesFromYarnBerry(content) {
-  const parse = await loadYarnBerry();
-  const lockfile = parse(content);
-
-  const result = new Set();
-  let workspaceCount = 0;
-  for (const [key, pkg] of Object.entries(lockfile)) {
-    if (key === '__metadata') continue;
-
-    // Skip workspace/link entries - flatlock only cares about external dependencies
-    const resolution = pkg.resolution || '';
-    if (resolution.startsWith('workspace:') ||
-        resolution.startsWith('portal:') ||
-        resolution.startsWith('link:')) {
-      workspaceCount++;
-      continue;
-    }
-
-    let name;
-    if (key.startsWith('@')) {
-      const idx = key.indexOf('@', 1);
-      name = key.slice(0, idx);
-    } else {
-      name = key.split('@')[0];
-    }
-    if (name && pkg.version) result.add(`${name}@${pkg.version}`);
-  }
-
-  return { packages: result, workspaceCount };
-}
-
-/**
- * Get packages set using js-yaml (pnpm)
- */
-async function getPackagesFromPnpm(content) {
-  const y = await loadYaml();
-  const lockfile = y.load(content);
-  const packages = lockfile.packages || {};
-
-  const result = new Set();
-  let workspaceCount = 0;
-  for (const [key, pkg] of Object.entries(packages)) {
-    // Skip link/file entries - flatlock only cares about external dependencies
-    // Keys can be: link:path, file:path, or @pkg@file:path
-    if (key.startsWith('link:') || key.startsWith('file:') ||
-        key.includes('@link:') || key.includes('@file:')) {
-      workspaceCount++;
-      continue;
-    }
-    // Also skip if resolution.type is 'directory' (workspace)
-    if (pkg.resolution?.type === 'directory') {
-      workspaceCount++;
-      continue;
-    }
-    // pnpm keys are like /lodash@4.17.21 or /@babel/core@7.0.0
-    const match = key.match(/^\/?(@?[^@]+)@(.+)$/);
-    if (match) result.add(`${match[1]}@${match[2]}`);
-  }
-
-  return { packages: result, workspaceCount };
-}
-
-/**
- * Get packages set with flatlock
- */
-async function getPackagesFromFlatlock(filepath) {
-  const result = new Set();
-  for await (const dep of flatlock.fromPath(filepath)) {
-    if (dep.name && dep.version) result.add(`${dep.name}@${dep.version}`);
-  }
-  return result;
-}
-
 /**
  * Get comparison parser name for type
  */
@@ -251,28 +18,6 @@ function getComparisonName(type) {
   }
 }
 
-/**
- * Get packages with comparison parser based on type
- */
-async function getPackagesFromComparison(type, content, filepath) {
-  switch (type) {
-    case 'npm': return getPackagesFromNpm(content, filepath);
-    case 'yarn-classic': return getPackagesFromYarnClassic(content);
-    case 'yarn-berry': return getPackagesFromYarnBerry(content);
-    case 'pnpm': return getPackagesFromPnpm(content);
-    default: return null;
-  }
-}
-
-/**
- * Compare two sets and return differences
- */
-function compareSets(setA, setB) {
-  const onlyInA = new Set([...setA].filter(x => !setB.has(x)));
-  const onlyInB = new Set([...setB].filter(x => !setA.has(x)));
-  return { onlyInA, onlyInB };
-}
-
 /**
  * Convert glob pattern to regex
  */
@@ -308,30 +53,21 @@ async function findFiles(dir, pattern) {
 }
 
 /**
- * Process a single lockfile - compare sets, not just counts
+ * Process a single lockfile using flatlock.compare()
  */
 async function processFile(filepath, baseDir) {
   try {
-    const content = await readFile(filepath, 'utf8');
-    const type = flatlock.detectType({ path: filepath, content });
+    const result = await flatlock.compare(filepath);
     const rel = baseDir ? filepath.replace(baseDir + '/', '') : filepath;
-    const comparisonName = getComparisonName(type);
-
-    const flatlockSet = await getPackagesFromFlatlock(filepath);
-    let comparisonResult;
+    const comparisonName = getComparisonName(result.type);
 
-    try {
-      comparisonResult = await getPackagesFromComparison(type, content, filepath);
-    } catch (err) {
-      comparisonResult = null;
-    }
-
-    if (!comparisonResult) {
+    if (result.identical === null) {
+      // Unsupported type or no comparison available
       return {
-        type,
+        type: result.type,
         path: rel,
         comparisonName,
-        flatlockCount: flatlockSet.size,
+        flatlockCount: result.flatlockCount,
         comparisonCount: null,
         workspaceCount: 0,
         identical: null,
@@ -340,20 +76,16 @@ async function processFile(filepath, baseDir) {
       };
     }
 
-    const { packages: comparisonSet, workspaceCount } = comparisonResult;
-    const { onlyInA: onlyInFlatlock, onlyInB: onlyInComparison } = compareSets(flatlockSet, comparisonSet);
-    const identical = onlyInFlatlock.size === 0 && onlyInComparison.size === 0;
-
     return {
-      type,
+      type: result.type,
       path: rel,
       comparisonName,
-      flatlockCount: flatlockSet.size,
-      comparisonCount: comparisonSet.size,
-      workspaceCount,
-      identical,
-      onlyInFlatlock,
-      onlyInComparison
+      flatlockCount: result.flatlockCount,
+      comparisonCount: result.comparisonCount,
+      workspaceCount: result.workspaceCount,
+      identical: result.identical,
+      onlyInFlatlock: result.onlyInFlatlock,
+      onlyInComparison: result.onlyInComparison
     };
   } catch (err) {
     const rel = baseDir ? filepath.replace(baseDir + '/', '') : filepath;
@@ -423,92 +155,87 @@ Examples:
   let matchCount = 0;
   let mismatchCount = 0;
 
-  try {
-    for (const file of files) {
-      const result = await processFile(file, baseDir);
+  for (const file of files) {
+    const result = await processFile(file, baseDir);
 
-      if (result.error) {
-        errorCount++;
-        if (!values.quiet) {
-          console.log(`\n❌ ERROR: ${result.path}`);
-          console.log(`   ${result.error}`);
-        }
-        continue;
+    if (result.error) {
+      errorCount++;
+      if (!values.quiet) {
+        console.log(`\n❌ ERROR: ${result.path}`);
+        console.log(`   ${result.error}`);
       }
+      continue;
+    }
 
-      fileCount++;
-      totalFlatlock += result.flatlockCount;
-      totalWorkspaces += result.workspaceCount || 0;
+    fileCount++;
+    totalFlatlock += result.flatlockCount;
+    totalWorkspaces += result.workspaceCount || 0;
 
-      if (result.comparisonCount === null) {
-        if (!values.quiet) {
-          console.log(`\n⚠️  ${result.path}`);
-          console.log(`   flatlock: ${result.flatlockCount} packages`);
-          console.log(`   ${result.comparisonName}: unavailable`);
-        }
-        continue;
+    if (result.comparisonCount === null) {
+      if (!values.quiet) {
+        console.log(`\n⚠️  ${result.path}`);
+        console.log(`   flatlock: ${result.flatlockCount} packages`);
+        console.log(`   ${result.comparisonName}: unavailable`);
       }
+      continue;
+    }
 
-      totalComparison += result.comparisonCount;
+    totalComparison += result.comparisonCount;
 
-      if (result.identical) {
-        matchCount++;
-        if (!values.quiet) {
-          const wsNote = result.workspaceCount > 0 ? ` (${result.workspaceCount} workspaces excluded)` : '';
-          console.log(`✓  ${result.path}${wsNote}`);
-          console.log(`   count: flatlock=${result.flatlockCount} ${result.comparisonName}=${result.comparisonCount}`);
-          console.log(`   sets:  identical`);
-        }
-      } else {
-        mismatchCount++;
-        console.log(`\n❌ ${result.path}`);
+    if (result.identical) {
+      matchCount++;
+      if (!values.quiet) {
+        const wsNote = result.workspaceCount > 0 ? ` (${result.workspaceCount} workspaces excluded)` : '';
+        console.log(`✓  ${result.path}${wsNote}`);
         console.log(`   count: flatlock=${result.flatlockCount} ${result.comparisonName}=${result.comparisonCount}`);
-        console.log(`   sets:  MISMATCH`);
-
-        if (result.onlyInFlatlock.size > 0) {
-          console.log(`   only in flatlock (${result.onlyInFlatlock.size}):`);
-          for (const pkg of [...result.onlyInFlatlock].slice(0, 10)) {
-            console.log(`     + ${pkg}`);
-          }
-          if (result.onlyInFlatlock.size > 10) {
-            console.log(`     ... and ${result.onlyInFlatlock.size - 10} more`);
-          }
+        console.log(`   sets:  identical`);
+      }
+    } else {
+      mismatchCount++;
+      console.log(`\n❌ ${result.path}`);
+      console.log(`   count: flatlock=${result.flatlockCount} ${result.comparisonName}=${result.comparisonCount}`);
+      console.log(`   sets:  MISMATCH`);
+
+      if (result.onlyInFlatlock.length > 0) {
+        console.log(`   only in flatlock (${result.onlyInFlatlock.length}):`);
+        for (const pkg of result.onlyInFlatlock.slice(0, 10)) {
+          console.log(`     + ${pkg}`);
         }
+        if (result.onlyInFlatlock.length > 10) {
+          console.log(`     ... and ${result.onlyInFlatlock.length - 10} more`);
+        }
+      }
 
-        if (result.onlyInComparison.size > 0) {
-          console.log(`   only in ${result.comparisonName} (${result.onlyInComparison.size}):`);
-          for (const pkg of [...result.onlyInComparison].slice(0, 10)) {
-            console.log(`     - ${pkg}`);
-          }
-          if (result.onlyInComparison.size > 10) {
-            console.log(`     ... and ${result.onlyInComparison.size - 10} more`);
-          }
+      if (result.onlyInComparison.length > 0) {
+        console.log(`   only in ${result.comparisonName} (${result.onlyInComparison.length}):`);
+        for (const pkg of result.onlyInComparison.slice(0, 10)) {
+          console.log(`     - ${pkg}`);
+        }
+        if (result.onlyInComparison.length > 10) {
+          console.log(`     ... and ${result.onlyInComparison.length - 10} more`);
         }
       }
     }
+  }
 
-    // Summary
-    console.log('\n' + '='.repeat(70));
-    console.log(`SUMMARY: ${fileCount} files, ${matchCount} identical, ${mismatchCount} mismatches, ${errorCount} errors`);
-    console.log(`  flatlock total:    ${totalFlatlock.toString().padStart(8)} packages`);
-    if (totalComparison > 0) {
-      console.log(`  comparison total:  ${totalComparison.toString().padStart(8)} packages`);
-    }
-    if (totalWorkspaces > 0) {
-      console.log(`  workspaces:        ${totalWorkspaces.toString().padStart(8)} excluded (local/workspace refs)`);
-    }
+  // Summary
+  console.log('\n' + '='.repeat(70));
+  console.log(`SUMMARY: ${fileCount} files, ${matchCount} identical, ${mismatchCount} mismatches, ${errorCount} errors`);
+  console.log(`  flatlock total:    ${totalFlatlock.toString().padStart(8)} packages`);
+  if (totalComparison > 0) {
+    console.log(`  comparison total:  ${totalComparison.toString().padStart(8)} packages`);
+  }
+  if (totalWorkspaces > 0) {
+    console.log(`  workspaces:        ${totalWorkspaces.toString().padStart(8)} excluded (local/workspace refs)`);
+  }
 
-    // Exit with error if any mismatches
-    if (mismatchCount > 0) {
-      process.exit(1);
-    }
-  } finally {
-    await cleanup();
+  // Exit with error if any mismatches
+  if (mismatchCount > 0) {
+    process.exit(1);
   }
 }
 
-main().catch(async err => {
-  await cleanup();
+main().catch(err => {
   console.error('Fatal error:', err.message);
   process.exit(1);
 });

package/dist/compare.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Compare flatlock output against established parser for a lockfile
+ * @param {string} filepath - Path to lockfile
+ * @param {CompareOptions} [options] - Options
+ * @returns {Promise<ComparisonResult>}
+ */
+export function compare(filepath: string, options?: CompareOptions): Promise<ComparisonResult>;
+/**
+ * Compare multiple lockfiles
+ * @param {string[]} filepaths - Paths to lockfiles
+ * @param {CompareOptions} [options] - Options
+ * @returns {AsyncGenerator<ComparisonResult & { filepath: string }>}
+ */
+export function compareAll(filepaths: string[], options?: CompareOptions): AsyncGenerator<ComparisonResult & {
+    filepath: string;
+}>;
+export type CompareOptions = {
+    /**
+     * - Temp directory for Arborist (npm only)
+     */
+    tmpDir?: string;
+};
+export type ComparisonResult = {
+    /**
+     * - Lockfile type
+     */
+    type: string;
+    /**
+     * - Whether flatlock matches comparison parser
+     */
+    identical: boolean | null;
+    /**
+     * - Number of packages found by flatlock
+     */
+    flatlockCount: number;
+    /**
+     * - Number of packages found by comparison parser
+     */
+    comparisonCount?: number;
+    /**
+     * - Number of workspace packages skipped
+     */
+    workspaceCount?: number;
+    /**
+     * - Packages only found by flatlock
+     */
+    onlyInFlatlock?: string[];
+    /**
+     * - Packages only found by comparison parser
+     */
+    onlyInComparison?: string[];
+};
+export type PackagesResult = {
+    /**
+     * - Set of package@version strings
+     */
+    packages: Set<string>;
+    /**
+     * - Number of workspace packages skipped
+     */
+    workspaceCount: number;
+};
+//# sourceMappingURL=compare.d.ts.map

package/dist/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.js"],"names":[],"mappings":"AAyMA;;;;;GAKG;AACH,kCAJW,MAAM,YACN,cAAc,GACZ,OAAO,CAAC,gBAAgB,CAAC,CA6CrC;AAED;;;;;GAKG;AACH,sCAJW,MAAM,EAAE,YACR,cAAc,GACZ,cAAc,CAAC,gBAAgB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAMnE;;;;;aAzPa,MAAM;;;;;;UAKN,MAAM;;;;eACN,OAAO,GAAG,IAAI;;;;mBACd,MAAM;;;;sBACN,MAAM;;;;qBACN,MAAM;;;;qBACN,MAAM,EAAE;;;;uBACR,MAAM,EAAE;;;;;;cAKR,GAAG,CAAC,MAAM,CAAC;;;;oBACX,MAAM"}

package/dist/detect.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Detect lockfile type from content and/or path
+ *
+ * Content is the primary signal - we actually parse the content to verify
+ * it's a valid lockfile of the detected type. This prevents spoofing attacks
+ * where malicious content contains detection markers in strings/comments.
+ *
+ * Path is only used as a fallback hint when content is not provided.
+ *
+ * @param {Object} options - Detection options
+ * @param {string} [options.path] - Path to the lockfile (optional hint)
+ * @param {string} [options.content] - Lockfile content (primary signal)
+ * @returns {LockfileType}
+ * @throws {Error} If unable to detect lockfile type
+ */
+export function detectType({ path, content }?: {
+    path?: string | undefined;
+    content?: string | undefined;
+}): LockfileType;
+/**
+ * @typedef {'npm' | 'pnpm' | 'yarn-classic' | 'yarn-berry'} LockfileType
+ */
+/**
+ * Lockfile type constants
+ */
+export const Type: Readonly<{
+    NPM: "npm";
+    PNPM: "pnpm";
+    YARN_CLASSIC: "yarn-classic";
+    YARN_BERRY: "yarn-berry";
+}>;
+export type LockfileType = "npm" | "pnpm" | "yarn-classic" | "yarn-berry";
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.js"],"names":[],"mappings":"AA8FA;;;;;;;;;;;;;;GAcG;AACH,+CALG;IAAyB,IAAI;IACJ,OAAO;CAChC,GAAU,YAAY,CAgDxB;AAtJD;;GAEG;AAEH;;GAEG;AACH;;;;;GAKG;2BAXU,KAAK,GAAG,MAAM,GAAG,cAAc,GAAG,YAAY"}