flatlock 1.1.0 → 1.3.0

package/bin/flatlock-cmp.js

@@ -5,18 +5,6 @@ import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import * as flatlock from '../src/index.js';
 
-/**
- * Get comparison parser name for type
- */
-function getComparisonName(type) {
-  switch (type) {
-    case 'npm': return '@npmcli/arborist';
-    case 'yarn-classic': return '@yarnpkg/lockfile';
-    case 'yarn-berry': return '@yarnpkg/parsers';
-    case 'pnpm': return 'js-yaml';
-    default: return 'unknown';
-  }
-}
 
 /**
  * Convert glob pattern to regex
@@ -59,18 +47,17 @@ async function processFile(filepath, baseDir) {
   try {
     const result = await flatlock.compare(filepath);
     const rel = baseDir ? filepath.replace(baseDir + '/', '') : filepath;
-    const comparisonName = getComparisonName(result.type);
 
-    if (result.identical === null) {
+    if (result.equinumerous === null) {
       // Unsupported type or no comparison available
       return {
         type: result.type,
         path: rel,
-        comparisonName,
+        source: result.source || 'unknown',
         flatlockCount: result.flatlockCount,
         comparisonCount: null,
         workspaceCount: 0,
-        identical: null,
+        equinumerous: null,
         onlyInFlatlock: null,
         onlyInComparison: null
       };
@@ -79,11 +66,11 @@ async function processFile(filepath, baseDir) {
     return {
       type: result.type,
       path: rel,
-      comparisonName,
+      source: result.source,
       flatlockCount: result.flatlockCount,
       comparisonCount: result.comparisonCount,
       workspaceCount: result.workspaceCount,
-      identical: result.identical,
+      equinumerous: result.equinumerous,
       onlyInFlatlock: result.onlyInFlatlock,
       onlyInComparison: result.onlyInComparison
     };
@@ -118,10 +105,21 @@ Options:
   -h, --help           Show this help
 
 Comparison parsers (workspace/link entries excluded from all):
-  npm:          @npmcli/arborist (loadVirtual)
+  npm:          @npmcli/arborist (preferred) or @cyclonedx/cyclonedx-npm
   yarn-classic: @yarnpkg/lockfile
   yarn-berry:   @yarnpkg/parsers
-  pnpm:         js-yaml
+  pnpm:         @pnpm/lockfile.fs (preferred) or js-yaml
+
+Result types:
+  ✓ equinumerous  Same packages in both (exact match)
+  ⊃ SUPERSET      flatlock found MORE packages (expected for pnpm)
+  ❌ MISMATCH      Unexpected difference (comparison found packages flatlock missed)
+
+Note on pnpm supersets:
+  flatlock performs full reachability analysis on lockfiles, finding all
+  transitive dependencies. pnpm's official tools don't enumerate all reachable
+  packages - they omit some transitive deps from their API output. When flatlock
+  finds MORE packages than pnpm, this is expected and correct behavior.
 
 Examples:
   flatlock-cmp package-lock.json
@@ -153,6 +151,7 @@ Examples:
   let fileCount = 0;
   let errorCount = 0;
   let matchCount = 0;
+  let supersetCount = 0;  // flatlock found more (expected for pnpm reachability)
   let mismatchCount = 0;
 
   for (const file of files) {
@@ -175,44 +174,61 @@ Examples:
       if (!values.quiet) {
         console.log(`\n⚠️  ${result.path}`);
         console.log(`   flatlock: ${result.flatlockCount} packages`);
-        console.log(`   ${result.comparisonName}: unavailable`);
+        console.log(`   ${result.source}: unavailable`);
       }
       continue;
     }
 
     totalComparison += result.comparisonCount;
 
-    if (result.identical) {
+    if (result.equinumerous) {
       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`);
+        console.log(`   count: flatlock=${result.flatlockCount} ${result.source}=${result.comparisonCount}`);
+        console.log(`   sets:  equinumerous`);
       }
     } 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`);
+      // Determine if this is a "superset" (flatlock found more, expected for pnpm)
+      // or a true "mismatch" (comparison found packages flatlock missed)
+      const isPnpm = result.type === 'pnpm' || result.path.includes('pnpm-lock');
+      const isSuperset = result.onlyInFlatlock.length > 0 && result.onlyInComparison.length === 0;
+
+      if (isPnpm && isSuperset) {
+        // Expected behavior: flatlock's reachability analysis found more packages
+        supersetCount++;
+        if (!values.quiet) {
+          const wsNote = result.workspaceCount > 0 ? ` (${result.workspaceCount} workspaces excluded)` : '';
+          console.log(`⊃  ${result.path}${wsNote}`);
+          console.log(`   count: flatlock=${result.flatlockCount} ${result.source}=${result.comparisonCount}`);
+          console.log(`   sets:  SUPERSET (+${result.onlyInFlatlock.length} reachable deps)`);
+          console.log(`   note:  flatlock's reachability analysis found transitive deps pnpm omits`);
         }
-      }
+      } else {
+        mismatchCount++;
+        console.log(`\n❌ ${result.path}`);
+        console.log(`   count: flatlock=${result.flatlockCount} ${result.source}=${result.comparisonCount}`);
+        console.log(`   sets:  MISMATCH`);
 
-      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.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.length > 10) {
-          console.log(`     ... and ${result.onlyInComparison.length - 10} more`);
+
+        if (result.onlyInComparison.length > 0) {
+          console.log(`   only in ${result.source} (${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`);
+          }
         }
       }
     }
@@ -220,7 +236,13 @@ Examples:
 
   // Summary
   console.log('\n' + '='.repeat(70));
-  console.log(`SUMMARY: ${fileCount} files, ${matchCount} identical, ${mismatchCount} mismatches, ${errorCount} errors`);
+  const summaryParts = [`${fileCount} files`, `${matchCount} equinumerous`];
+  if (supersetCount > 0) {
+    summaryParts.push(`${supersetCount} supersets`);
+  }
+  summaryParts.push(`${mismatchCount} mismatches`, `${errorCount} errors`);
+  console.log(`SUMMARY: ${summaryParts.join(', ')}`);
+
   console.log(`  flatlock total:    ${totalFlatlock.toString().padStart(8)} packages`);
   if (totalComparison > 0) {
     console.log(`  comparison total:  ${totalComparison.toString().padStart(8)} packages`);
@@ -228,8 +250,12 @@ Examples:
   if (totalWorkspaces > 0) {
     console.log(`  workspaces:        ${totalWorkspaces.toString().padStart(8)} excluded (local/workspace refs)`);
   }
+  if (supersetCount > 0) {
+    console.log(`  supersets:         ${supersetCount.toString().padStart(8)} (flatlock found more via reachability)`);
+  }
 
-  // Exit with error if any mismatches
+  // Exit with error only for true mismatches (not supersets)
+  // Supersets are expected: flatlock's reachability analysis is more thorough
   if (mismatchCount > 0) {
     process.exit(1);
   }

package/bin/flatlock.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * flatlock - Get dependencies from a lockfile
+ *
+ * For monorepo workspaces, outputs the production dependencies of a workspace.
+ * For standalone packages, outputs all production dependencies.
+ *
+ * Usage:
+ *   flatlock <lockfile>                           # all deps (names only)
+ *   flatlock <lockfile> --specs                   # name@version
+ *   flatlock <lockfile> --json                    # JSON array
+ *   flatlock <lockfile> --specs --json            # JSON with versions
+ *   flatlock <lockfile> --specs --ndjson          # streaming NDJSON
+ *   flatlock <lockfile> --full --ndjson           # full metadata streaming
+ */
+
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { FlatlockSet } from '../src/set.js';
+
+const { values, positionals } = parseArgs({
+  options: {
+    workspace: { type: 'string', short: 'w' },
+    dev: { type: 'boolean', default: false },
+    peer: { type: 'boolean', default: true },
+    specs: { type: 'boolean', short: 's', default: false },
+    json: { type: 'boolean', default: false },
+    ndjson: { type: 'boolean', default: false },
+    full: { type: 'boolean', default: false },
+    help: { type: 'boolean', short: 'h' }
+  },
+  allowPositionals: true
+});
+
+if (values.help || positionals.length === 0) {
+  console.log(`flatlock - Get dependencies from a lockfile
+
+Usage:
+  flatlock <lockfile>
+  flatlock <lockfile> --workspace <path>
+
+Options:
+  -w, --workspace <path>  Workspace path within monorepo
+  -s, --specs             Include version (name@version or {name,version})
+  --json                  Output as JSON array
+  --ndjson                Output as newline-delimited JSON (streaming)
+  --full                  Include all metadata (integrity, resolved)
+  --dev                   Include dev dependencies (default: false)
+  --peer                  Include peer dependencies (default: true)
+  -h, --help              Show this help
+
+Output formats:
+  (default)               package names, one per line
+  --specs                 package@version, one per line
+  --json                  ["package", ...]
+  --specs --json          [{"name":"...","version":"..."}, ...]
+  --full --json           [{"name":"...","version":"...","integrity":"...","resolved":"..."}, ...]
+  --ndjson                "package" per line
+  --specs --ndjson        {"name":"...","version":"..."} per line
+  --full --ndjson         {"name":"...","version":"...","integrity":"...","resolved":"..."} per line
+
+Examples:
+  flatlock package-lock.json
+  flatlock package-lock.json --specs
+  flatlock package-lock.json --specs --json
+  flatlock package-lock.json --full --ndjson | jq -c 'select(.name | startswith("@babel"))'
+  flatlock pnpm-lock.yaml -w packages/core -s --ndjson`);
+  process.exit(values.help ? 0 : 1);
+}
+
+if (values.json && values.ndjson) {
+  console.error('Error: --json and --ndjson are mutually exclusive');
+  process.exit(1);
+}
+
+// --full implies --specs
+if (values.full) {
+  values.specs = true;
+}
+
+const lockfilePath = positionals[0];
+
+/**
+ * Format a single dependency based on output options
+ * @param {{ name: string, version: string, integrity?: string, resolved?: string }} dep
+ * @param {{ specs: boolean, full: boolean }} options
+ * @returns {string | object}
+ */
+function formatDep(dep, { specs, full }) {
+  if (full) {
+    const obj = { name: dep.name, version: dep.version };
+    if (dep.integrity) obj.integrity = dep.integrity;
+    if (dep.resolved) obj.resolved = dep.resolved;
+    return obj;
+  }
+  if (specs) {
+    return { name: dep.name, version: dep.version };
+  }
+  return dep.name;
+}
+
+/**
+ * Output dependencies in the requested format
+ * @param {Iterable<{ name: string, version: string, integrity?: string, resolved?: string }>} deps
+ * @param {{ specs: boolean, json: boolean, ndjson: boolean, full: boolean }} options
+ */
+function outputDeps(deps, { specs, json, ndjson, full }) {
+  const sorted = [...deps].sort((a, b) => a.name.localeCompare(b.name));
+
+  if (json) {
+    const data = sorted.map(d => formatDep(d, { specs, full }));
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (ndjson) {
+    for (const d of sorted) {
+      console.log(JSON.stringify(formatDep(d, { specs, full })));
+    }
+    return;
+  }
+
+  // Plain text
+  for (const d of sorted) {
+    console.log(specs ? `${d.name}@${d.version}` : d.name);
+  }
+}
+
+try {
+  const lockfile = await FlatlockSet.fromPath(lockfilePath);
+  let deps;
+
+  if (values.workspace) {
+    const repoDir = dirname(lockfilePath);
+    const workspacePkgPath = join(repoDir, values.workspace, 'package.json');
+    const workspacePkg = JSON.parse(readFileSync(workspacePkgPath, 'utf8'));
+
+    deps = await lockfile.dependenciesOf(workspacePkg, {
+      workspacePath: values.workspace,
+      repoDir,
+      dev: values.dev,
+      peer: values.peer
+    });
+  } else {
+    deps = lockfile;
+  }
+
+  outputDeps(deps, {
+    specs: values.specs,
+    json: values.json,
+    ndjson: values.ndjson,
+    full: values.full
+  });
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flatlock",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "The Matlock of lockfile parsers - extracts packages without building dependency graphs",
   "keywords": [
     "lockfile",
@@ -35,15 +35,19 @@
   },
   "main": "src/index.js",
   "bin": {
-    "flatlock-cmp": "./bin/flatlock-cmp.js"
+    "flatlock": "./bin/flatlock.js",
+    "flatlock-cmp": "./bin/flatlock-cmp.js",
+    "flatcover": "./bin/flatcover.js"
   },
   "files": [
     "src",
     "dist",
-    "bin"
+    "bin/flatlock.js",
+    "bin/flatlock-cmp.js",
+    "bin/flatcover.js"
   ],
   "scripts": {
-    "test": "node --test ./test/*.test.js",
+    "test": "node --test ./test/*.test.js ./test/**/*.test.js",
     "test:coverage": "c8 node --test ./test/*.test.js",
     "build:types": "tsc",
     "lint": "biome lint src test",
@@ -53,29 +57,38 @@
     "format:check": "biome format src test",
     "check": "biome check src test && pnpm run build:types",
     "check:fix": "biome check --write src test",
+    "build:ncc": "./bin/ncc.sh",
     "prepublishOnly": "pnpm run build:types"
   },
   "dependencies": {
     "@yarnpkg/lockfile": "^1.1.0",
     "@yarnpkg/parsers": "^3.0.3",
-    "js-yaml": "^4.1.1"
+    "js-yaml": "^4.1.1",
+    "undici": "^7.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.8",
-    "@pnpm/lockfile-file": "^9.0.0",
+    "@vercel/ncc": "^0.38.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.2",
     "c8": "^10.1.3",
+    "chalk": "^5.6.2",
+    "fast-glob": "^3.3.3",
+    "jackspeak": "^4.1.1",
     "markdownlint-cli2": "^0.17.2",
     "snyk-nodejs-lockfile-parser": "^1.55.0",
+    "tinyexec": "^1.0.2",
     "typescript": "^5.7.2"
   },
   "optionalDependencies": {
-    "@npmcli/arborist": "^9.1.9"
+    "@cyclonedx/cdxgen": "^11.3.3",
+    "@npmcli/arborist": "^9.1.9",
+    "@pnpm/lockfile.fs": "^1001.0.0",
+    "@yarnpkg/core": "^4.5.0"
   },
   "packageManager": "pnpm@10.25.0",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "c8": {
     "all": true,