plexus-peers 0.2.0

package/README.md

@@ -0,0 +1,85 @@
+# Plexus
+
+CLI and a small web UI to inspect **direct dependencies** from a `package.json`: peer dependency ranges vs what is installed, optional **BundlePhobia**-style bundle size hints, and a **`--fix`** mode that queries npm for upgrade and cascade notes.
+
+Requires **Node.js 18+** (uses the built-in `fetch` API).
+
+The npm package is **`plexus-peers`** (the short name `plexus` is already used on the registry by another project).
+
+## Install
+
+From npm:
+
+```bash
+npx plexus-peers --help
+```
+
+From a clone of this repo:
+
+```bash
+npm install
+node bin/plexus.js --help
+```
+
+## CLI
+
+Run from a project that has `package.json` (and usually `node_modules` after `npm install`):
+
+```bash
+npx plexus-peers                      # Terminal report for the current directory
+npx plexus-peers --dir ./my-app       # Another project root
+npx plexus-peers -f ./path/to/package.json
+```
+
+| Option | Description |
+|--------|-------------|
+| `--html` | Write an HTML report (`dep-graph.html` in the project root, or use `--out`) |
+| `--out <path>` | HTML output path (with `--html`) |
+| `--conflicts-only` | Only list packages that have peer issues |
+| `--fix` | Call `npm` for latest metadata and print resolution hints (chatty; avoid on CI if logs matter) |
+| `--bundlesize` | With `--html`, query [BundlePhobia](https://bundlephobia.com/) per direct dependency (slow, rate limits may apply) |
+| `--pkg <name>` | Focus on one direct dependency and related peer rows |
+
+Examples:
+
+```bash
+npx plexus-peers --html
+npx plexus-peers --html --fix --bundlesize --dir ./my-app
+```
+
+## Web UI (`serve`)
+
+Starts a local server with a page to **upload** a `package.json`. The report is generated from the **npm registry** (semver resolution for each direct dependency). There is **no** local `node_modules`, so disk sizes are absent and only dependencies declared in the manifest contribute resolved versions for peers.
+
+```bash
+npx plexus-peers serve
+# http://127.0.0.1:3847  (override with --port)
+```
+
+From the repo you can also run:
+
+```bash
+npm start
+```
+
+Optional checkboxes on the page match `--fix` and `--bundlesize`.
+
+## CLI vs upload
+
+| | CLI (filesystem) | Web upload |
+|--|------------------|------------|
+| **Versions** | Read from `node_modules` | Resolved from registry against ranges in `package.json` |
+| **Disk size** | `du` on `node_modules` entries | Not available |
+| **Peers only transitive** | Can still be read from disk if present | Only if that package is also a direct dependency |
+
+## Development
+
+```bash
+npm install
+npm run plexus -- --help
+npm start   # serve UI on default port
+```
+
+## License
+
+MIT

package/bin/plexus.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { runFilesystemAnalysis } = require('../lib/engine');
+const { startServer } = require('../lib/server');
+
+function printHelp() {
+  console.log(`
+Plexus — peer dependencies, sizes, resolution hints
+
+Usage:
+  npx plexus-peers [options]              Analyze package.json in current directory
+  npx plexus-peers serve [options]        Start upload UI + API
+
+Options:
+  --dir, -C <path>     Project root (contains package.json and node_modules)
+  --file, -f <path>    Path to package.json (root = its directory)
+  --html               Write HTML report (dep-graph.html in project root)
+  --out <path>         HTML output path (with --html)
+  --conflicts-only     Terminal: only packages with peer issues
+  --fix                Query npm for upgrade / cascade hints (noisy on CI)
+  --bundlesize         With --html: fetch gzip sizes from BundlePhobia (slow)
+  --pkg <name>         Focus on one direct dependency and its peers
+
+Serve:
+  --port <n>           Port (default: 3847)
+
+Examples:
+  npx plexus-peers --html --dir ./my-app
+  npx plexus-peers serve --port 3847
+`);
+}
+
+function parseArgv(argv) {
+  const out = {
+    command: 'analyze',
+    rootDir: null,
+    packageJsonPath: null,
+    port: 3847,
+    flags: {
+      conflictsOnly: false,
+      html: false,
+      fix: false,
+      bundleSize: false,
+      focusPkg: null,
+      outFile: null,
+    },
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === 'serve' || a === 'web') {
+      out.command = 'serve';
+      continue;
+    }
+    if (a === '--help' || a === '-h') {
+      out.help = true;
+      continue;
+    }
+    if (a === '--dir' || a === '-C') {
+      out.rootDir = path.resolve(argv[++i] ?? '');
+      continue;
+    }
+    if (a === '--file' || a === '-f') {
+      out.packageJsonPath = path.resolve(argv[++i] ?? '');
+      continue;
+    }
+    if (a === '--port') {
+      out.port = Number(argv[++i]) || 3847;
+      continue;
+    }
+    if (a === '--out') {
+      out.flags.outFile = path.resolve(argv[++i] ?? '');
+      continue;
+    }
+    if (a === '--pkg') {
+      out.flags.focusPkg = argv[++i] ?? null;
+      continue;
+    }
+    if (a === '--conflicts-only') {
+      out.flags.conflictsOnly = true;
+      continue;
+    }
+    if (a === '--html') {
+      out.flags.html = true;
+      continue;
+    }
+    if (a === '--fix') {
+      out.flags.fix = true;
+      continue;
+    }
+    if (a === '--bundlesize') {
+      out.flags.bundleSize = true;
+      continue;
+    }
+    if (a.startsWith('-')) {
+      console.error(`Unknown option: ${a}\nRun npx plexus-peers --help`);
+      process.exitCode = 1;
+      return null;
+    }
+  }
+
+  if (out.packageJsonPath) {
+    out.rootDir = path.dirname(out.packageJsonPath);
+  }
+  if (!out.rootDir) {
+    out.rootDir = process.cwd();
+  }
+
+  return out;
+}
+
+async function main() {
+  const parsed = parseArgv(process.argv.slice(2));
+  if (!parsed) return;
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  if (parsed.command === 'serve') {
+    startServer({ port: parsed.port });
+    return;
+  }
+
+  await runFilesystemAnalysis({ rootDir: parsed.rootDir, flags: parsed.flags });
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/lib/ansi.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+};
+
+function color(str, ...codes) {
+  return codes.map(code => c[code]).join('') + str + c.reset;
+}
+
+module.exports = { color };

package/lib/engine.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * Plexus engine — dependency graph + peer conflict detection (filesystem or registry).
+ * Re-exports modular pieces; implementation lives in ./ansi, ./format, ./graph, etc.
+ */
+
+const { color } = require('./ansi');
+const { formatBytes } = require('./format');
+const { createFsContext, buildGraph } = require('./graph');
+const { printGraph, printSummary } = require('./terminal');
+const { resolveConflicts } = require('./fix');
+const { queryNpm, getBundleSize } = require('./npm');
+const { renderHtml } = require('./render-html');
+const { openHtmlReport, runFilesystemAnalysis, runRegistryAnalysis } = require('./run-analysis');
+
+module.exports = {
+  color,
+  formatBytes,
+  buildGraph,
+  createFsContext,
+  printGraph,
+  printSummary,
+  resolveConflicts,
+  queryNpm,
+  renderHtml,
+  getBundleSize,
+  runFilesystemAnalysis,
+  runRegistryAnalysis,
+  openHtmlReport,
+};

package/lib/fix.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { color } = require('./ansi');
+const { satisfies } = require('./graph');
+const { queryNpm } = require('./npm');
+
+/**
+ * For each real conflict (version mismatch, not just missing optional):
+ *  1. Query npm for the latest version of the conflicting package.
+ *  2. Check if latest fixes the conflict (its new peer range accepts the installed version).
+ *  3. Check if latest introduces NEW conflicts (cascade detection).
+ */
+function resolveConflicts(graph, directDeps, getInstalledVersion, options = {}) {
+  const silent = options.silent === true;
+  const log = (...args) => {
+    if (!silent) console.log(...args);
+  };
+  const write = (...args) => {
+    if (!silent) process.stdout.write(...args);
+  };
+
+  const directSet = new Set(Object.keys(directDeps));
+
+  const conflicts = [];
+  for (const [pkgName, info] of Object.entries(graph)) {
+    if (!directSet.has(pkgName)) continue;
+    for (const peer of info.peerDeps) {
+      if (!peer.ok && peer.installed) {
+        conflicts.push({
+          pkg: pkgName,
+          peer: peer.name,
+          range: peer.range,
+          installed: peer.installed,
+        });
+      }
+    }
+  }
+
+  if (conflicts.length === 0) return { resolutions: {}, cascades: [], suggestedDeps: null };
+
+  const pkgsToCheck = [...new Set(conflicts.map(c => c.pkg))];
+
+  log(color(`\nQuerying npm for ${pkgsToCheck.length} package(s)…`, 'gray'));
+
+  const resolutions = {};
+
+  for (const pkg of pkgsToCheck) {
+    write(`  ${color(pkg, 'cyan')} … `);
+    const info = queryNpm(pkg);
+    if (!info) {
+      log(color('not found on npm', 'yellow'));
+      continue;
+    }
+
+    const latest = info['dist-tags']?.latest;
+    if (!latest) {
+      log(color('no dist-tags.latest', 'yellow'));
+      continue;
+    }
+
+    const newPeerDeps = info.peerDependencies ?? {};
+    const currentVersion = directDeps[pkg];
+
+    const fixes = conflicts
+      .filter(c => c.pkg === pkg)
+      .filter(c => {
+        const newRange = newPeerDeps[c.peer];
+        if (!newRange) return true;
+        return satisfies(c.installed, newRange);
+      })
+      .map(c => c.peer);
+
+    const stillConflicts = conflicts
+      .filter(c => c.pkg === pkg && !fixes.includes(c.peer))
+      .map(c => c.peer);
+
+    const cascades = Object.entries(newPeerDeps)
+      .map(([peerName, peerRange]) => {
+        const installedVer = getInstalledVersion(peerName);
+        if (!installedVer) return null;
+        const ok = satisfies(installedVer, peerRange);
+        return ok ? null : { peerName, peerRange, installedVer };
+      })
+      .filter(Boolean);
+
+    log(
+      latest === currentVersion.replace(/[\^~>=<]/g, '')
+        ? color(`already latest (v${latest})`, 'gray')
+        : color(`v${currentVersion} → v${latest}`, 'green'),
+    );
+
+    resolutions[pkg] = {
+      current: currentVersion,
+      latest,
+      fixes,
+      stillConflicts,
+      cascades,
+      newPeerDeps,
+    };
+  }
+
+  const upgrades = Object.fromEntries(
+    Object.entries(resolutions).map(([pkg, r]) => [pkg, r.latest]),
+  );
+
+  return { resolutions, upgrades };
+}
+
+module.exports = { resolveConflicts };

package/lib/format.js

@@ -0,0 +1,17 @@
+'use strict';
+
+function formatBytes(bytes) {
+  if (bytes === null || bytes === undefined) return null;
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+function sizeClass(bytes) {
+  if (!bytes) return '';
+  if (bytes > 5 * 1024 * 1024) return 'size-large';
+  if (bytes > 1 * 1024 * 1024) return 'size-medium';
+  return 'size-small';
+}
+
+module.exports = { formatBytes, sizeClass };

package/lib/graph.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const semver = require('semver');
+
+function getDiskSize(pkgName, nodeModulesPath) {
+  const pkgPath = path.join(nodeModulesPath, pkgName);
+  try {
+    const out = execFileSync('du', ['-sk', pkgPath], {
+      encoding: 'utf8',
+      timeout: 8000,
+      maxBuffer: 256 * 1024,
+    });
+    const kb = parseInt(out.split(/\s/)[0], 10);
+    return isNaN(kb) ? null : kb * 1024;
+  } catch {
+    return null;
+  }
+}
+
+function createFsContext(rootDir) {
+  const nodeModulesPath = path.join(rootDir, 'node_modules');
+  function readPkg(pkgName) {
+    const pkgPath = path.join(nodeModulesPath, pkgName, 'package.json');
+    try {
+      return JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+  function getInstalledVersion(pkgName) {
+    return readPkg(pkgName)?.version ?? null;
+  }
+  return {
+    nodeModulesPath,
+    readPkg,
+    getDiskSize: pkgName => getDiskSize(pkgName, nodeModulesPath),
+    getInstalledVersion,
+  };
+}
+
+function satisfies(installedVersion, requiredRange) {
+  if (!installedVersion) return false;
+  try {
+    const coerced = semver.coerce(installedVersion);
+    if (!coerced) return false;
+    return semver.satisfies(coerced, requiredRange, { includePrerelease: true });
+  } catch {
+    return false;
+  }
+}
+
+function buildGraph(directDeps, ctx) {
+  const { readPkg, getDiskSize, getInstalledVersion } = ctx;
+  const graph = {};
+
+  const toProcess = [...Object.keys(directDeps)];
+  const visited = new Set();
+
+  while (toProcess.length > 0) {
+    const pkgName = toProcess.shift();
+    if (visited.has(pkgName)) continue;
+    visited.add(pkgName);
+
+    const pkg = readPkg(pkgName);
+    if (!pkg) {
+      graph[pkgName] = { version: null, missing: true, peerDeps: [], requiredBy: [] };
+      continue;
+    }
+
+    const peerDeps = pkg.peerDependencies ?? {};
+    const peerEntries = Object.entries(peerDeps).map(([name, range]) => {
+      const installed = getInstalledVersion(name);
+      const ok = satisfies(installed, range);
+      return { name, range, installed, ok };
+    });
+
+    graph[pkgName] = {
+      version: pkg.version,
+      missing: false,
+      diskSize: getDiskSize(pkgName),
+      peerDeps: peerEntries,
+      requiredBy: [],
+    };
+
+    for (const { name } of peerEntries) {
+      if (!graph[name])
+        graph[name] = { version: null, missing: false, peerDeps: [], requiredBy: [] };
+      if (!graph[name].requiredBy.includes(pkgName)) {
+        graph[name].requiredBy.push(pkgName);
+      }
+    }
+  }
+
+  return graph;
+}
+
+module.exports = { createFsContext, buildGraph, satisfies };

package/lib/html-escape.js

@@ -0,0 +1,22 @@
+'use strict';
+
+function escapeHtml(s) {
+  if (s == null || s === '') return '';
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function npmPackageUrl(name) {
+  return `https://www.npmjs.com/package/${encodeURIComponent(String(name))}`;
+}
+
+/** Safe `id` / fragment slug for package names (not HTML-escaped — use only in id/href fragments). */
+function pkgSlugForDom(name) {
+  return String(name).replace(/[@/]/g, '-').replace(/[^a-zA-Z0-9._-]/g, '-');
+}
+
+module.exports = { escapeHtml, npmPackageUrl, pkgSlugForDom };

package/lib/npm.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+const semver = require('semver');
+
+function queryNpm(pkg) {
+  try {
+    const out = execFileSync('npm', ['info', pkg, '--json'], {
+      encoding: 'utf8',
+      timeout: 12000,
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return out ? JSON.parse(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function getBundleSize(pkgName, version) {
+  try {
+    const url = `https://bundlephobia.com/api/size?package=${encodeURIComponent(pkgName)}@${version}`;
+    const res = await fetch(url, { signal: AbortSignal.timeout(10000) });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return { size: data.size, gzip: data.gzip };
+  } catch {
+    return null;
+  }
+}
+
+async function fetchResolvedPackageManifest(name, range) {
+  const url = `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+  const res = await fetch(url, { signal: AbortSignal.timeout(20000) });
+  if (!res.ok) return null;
+  const data = await res.json();
+  const versions = Object.keys(data.versions || {});
+  const best = semver.maxSatisfying(versions, range, { includePrerelease: true });
+  if (!best) return null;
+  return data.versions[best];
+}
+
+function registryFetchConcurrency() {
+  const n = Number(process.env.PLEXUS_REGISTRY_CONCURRENCY || 10);
+  return Math.max(1, Math.min(50, n > 0 ? n : 10));
+}
+
+async function createRegistryContext(directDeps) {
+  const pkgs = new Map();
+  const names = Object.keys(directDeps);
+  const limit = registryFetchConcurrency();
+  for (let i = 0; i < names.length; i += limit) {
+    const batch = names.slice(i, i + limit);
+    await Promise.all(
+      batch.map(async name => {
+        try {
+          const manifest = await fetchResolvedPackageManifest(name, directDeps[name]);
+          pkgs.set(name, manifest);
+        } catch {
+          pkgs.set(name, null);
+        }
+      }),
+    );
+  }
+
+  function readPkg(pkgName) {
+    return pkgs.get(pkgName) ?? null;
+  }
+  function getInstalledVersion(pkgName) {
+    return readPkg(pkgName)?.version ?? null;
+  }
+  return {
+    readPkg,
+    getDiskSize: () => null,
+    getInstalledVersion,
+  };
+}
+
+module.exports = {
+  queryNpm,
+  getBundleSize,
+  fetchResolvedPackageManifest,
+  createRegistryContext,
+  registryFetchConcurrency,
+};