@yob/depcollector 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# depcollector
+
+A CLI tool that snapshots the state of your npm dependencies. It reads your
+`package.json` and `package-lock.json`, queries the npm registry, and outputs
+a JSON report containing each dependency's locked version, its release date,
+and the latest available version with its release date. It also captures the
+current git SHA and commit timestamp.
+
+## Why?
+
+Keeping dependencies up to date is important, but it's hard to track *how*
+out of date they are across projects over time. depcollector produces a
+structured snapshot you can store (e.g. in S3) and trend over time to answer
+questions like:
+
+- How old are my locked dependency versions?
+- How far behind latest is each dependency?
+- Are things getting better or worse over time?
+
+## Requirements
+
+- Node.js >= 20
+- A `package.json` and `package-lock.json` in the target directory
+- A git repository (for SHA and commit timestamp)
+
+## Installation
+
+```bash
+npm install -g depcollector
+```
+
+Or run directly with npx:
+
+```bash
+npx depcollector
+```
+
+## Usage
+
+Run in any directory containing a `package.json` and `package-lock.json`:
+
+```bash
+depcollector
+```
+
+This prints a JSON report to stdout:
+
+```json
+{
+  "ecosystem": "npm",
+  "collectedAt": "2026-02-08T11:24:42.590Z",
+  "gitSha": "c75e008...",
+  "gitTimestamp": "2026-02-08T22:24:33+11:00",
+  "dependencies": [
+    {
+      "name": "typescript",
+      "direct": true,
+      "currentVersion": "5.9.3",
+      "currentVersionDate": "2025-09-30T21:19:38.784Z",
+      "latestVersion": "5.9.3",
+      "latestVersionDate": "2025-09-30T21:19:38.784Z"
+    }
+  ]
+}
+```
+
+### `--at-commit`
+
+By default, "latest version" means the latest version available right now. If
+you want to know what the latest version was *at the time of the commit*
+instead, use the `--at-commit` flag:
+
+```bash
+depcollector --at-commit
+```
+
+This caps the "latest version" to the most recent release that existed at the
+git commit timestamp. This is useful for historical analysis -- for example,
+running depcollector against older commits to understand how out of date
+dependencies were at that point in time, without the answer being skewed by
+versions released after the commit.
+
+### `--transitive`
+
+By default, only direct dependencies (those listed in `dependencies` and
+`devDependencies` in `package.json`) are included. Use `--transitive` to
+include all transitive dependencies from the lockfile as well:
+
+```bash
+depcollector --transitive
+```
+
+Each dependency in the output includes a `"direct"` field indicating whether
+it is a direct dependency (`true`) or a transitive one (`false`). If the same
+package appears at multiple versions in the dependency tree, each distinct
+version is reported separately.
+
+### `--project-name <name>`
+
+Include a project name in the output. Useful for distinguishing reports when
+collecting dependency data across multiple projects:
+
+```bash
+depcollector --project-name myapp
+```
+
+This adds a `"projectName"` key to the top level of the JSON output.
+
+### `--manifest-path <path>`
+
+Include the in-repo path to the manifest in the output. This is intended for
+monorepos where dependency data might be collected for multiple packages:
+
+```bash
+depcollector --manifest-path packages/api/package.json
+```
+
+This adds a `"manifestPath"` key to the top level of the JSON output. The
+value is not validated -- it can be any string.
+
+### Saving output
+
+The output is plain JSON on stdout, so you can pipe it wherever you like:
+
+```bash
+# Save to a file
+depcollector > deps-snapshot.json
+
+# Upload to S3
+depcollector | aws s3 cp - s3://my-bucket/deps/$(date +%Y-%m-%d).json
+
+# Pretty-print with jq
+depcollector | jq .
+```
+
+## Output format
+
+| Field | Description |
+|---|---|
+| `ecosystem` | Always `"npm"` |
+| `projectName` | Project name (present when `--project-name` is used) |
+| `manifestPath` | In-repo manifest path (present when `--manifest-path` is used) |
+| `collectedAt` | ISO 8601 timestamp of when the report was generated |
+| `gitSha` | The current HEAD commit SHA |
+| `gitTimestamp` | The commit timestamp of HEAD |
+| `dependencies[]` | Array of dependency info objects |
+| `dependencies[].name` | Package name |
+| `dependencies[].direct` | `true` for direct dependencies, `false` for transitive |
+| `dependencies[].currentVersion` | Version locked in package-lock.json |
+| `dependencies[].currentVersionDate` | Release date of the locked version |
+| `dependencies[].latestVersion` | Latest available version (or latest as of commit with `--at-commit`) |
+| `dependencies[].latestVersionDate` | Release date of the latest version |
+
+## License
+
+MIT
+
+## Author
+
+[James Healy](https://yob.id.au)

package/bin/depcollector.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/git.d.ts

@@ -0,0 +1,4 @@
+export declare function getGitInfo(): {
+    sha: string;
+    timestamp: string;
+};

package/dist/git.js

@@ -0,0 +1,8 @@
+import { execSync } from 'node:child_process';
+export function getGitInfo() {
+    const sha = execSync('git rev-parse HEAD', { encoding: 'utf-8' }).trim();
+    const timestamp = execSync('git log -1 --format=%cI', {
+        encoding: 'utf-8',
+    }).trim();
+    return { sha, timestamp };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,100 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { program } from 'commander';
+import { getPackageInfo } from './registry.js';
+import { getGitInfo } from './git.js';
+const CONCURRENCY = 5;
+async function loadJson(filePath) {
+    const content = await readFile(filePath, 'utf-8');
+    return JSON.parse(content);
+}
+function getLockedVersions(packageJson, lockfile, transitive) {
+    if (!lockfile.lockfileVersion || lockfile.lockfileVersion < 2) {
+        throw new Error(`package-lock.json lockfileVersion ${lockfile.lockfileVersion ?? 1} is not supported. ` +
+            'Please regenerate your lockfile with npm 7+ (lockfileVersion 2 or 3).');
+    }
+    if (!lockfile.packages) {
+        throw new Error("package-lock.json has no 'packages' field.");
+    }
+    if (transitive) {
+        return getAllLockedVersions(lockfile.packages);
+    }
+    const allDeps = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
+    };
+    const result = [];
+    for (const name of Object.keys(allDeps)) {
+        const entry = lockfile.packages[`node_modules/${name}`];
+        if (entry?.version) {
+            result.push({ name, version: entry.version });
+        }
+    }
+    return result;
+}
+function getAllLockedVersions(packages) {
+    const seen = new Set();
+    const result = [];
+    for (const [path, entry] of Object.entries(packages)) {
+        if (!path.startsWith('node_modules/') || !entry.version)
+            continue;
+        // Extract package name from the last node_modules/ segment
+        // e.g. "node_modules/a/node_modules/@scope/b" -> "@scope/b"
+        const name = path.substring(path.lastIndexOf('node_modules/') + 13);
+        // Deduplicate by name+version to avoid redundant registry calls
+        const key = `${name}@${entry.version}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push({ name, version: entry.version });
+        }
+    }
+    return result;
+}
+async function processInBatches(locked, directNames, concurrency, cutoff) {
+    const results = [];
+    for (let i = 0; i < locked.length; i += concurrency) {
+        const batch = locked.slice(i, i + concurrency);
+        const batchResults = await Promise.all(batch.map((dep) => getPackageInfo(dep.name, dep.version, directNames.has(dep.name), cutoff)));
+        results.push(...batchResults);
+    }
+    return results;
+}
+program
+    .name('depcollector')
+    .description('Collect dependency version and age information from package.json and package-lock.json')
+    .option('--at-commit', 'Cap latest version to what was available at the time of the commit')
+    .option('--transitive', 'Include transitive dependencies')
+    .option('--project-name <name>', 'Include a project name in the output')
+    .option('--manifest-path <path>', 'Include the in-repo path to the manifest in the output')
+    .parse();
+async function main() {
+    const opts = program.opts();
+    const cwd = process.cwd();
+    const [packageJson, lockfile] = await Promise.all([
+        loadJson(join(cwd, 'package.json')),
+        loadJson(join(cwd, 'package-lock.json')),
+    ]);
+    const locked = getLockedVersions(packageJson, lockfile, opts.transitive ?? false);
+    locked.sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version));
+    const directNames = new Set(Object.keys({
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
+    }));
+    const gitInfo = getGitInfo();
+    const cutoff = opts.atCommit ? new Date(gitInfo.timestamp) : undefined;
+    const dependencies = await processInBatches(locked, directNames, CONCURRENCY, cutoff);
+    const result = {
+        ecosystem: 'npm',
+        ...(opts.projectName && { projectName: opts.projectName }),
+        ...(opts.manifestPath && { manifestPath: opts.manifestPath }),
+        collectedAt: new Date().toISOString(),
+        gitSha: gitInfo.sha,
+        gitTimestamp: gitInfo.timestamp,
+        dependencies,
+    };
+    console.log(JSON.stringify(result, null, 2));
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/registry.d.ts

@@ -0,0 +1,2 @@
+import type { DependencyInfo } from './types.js';
+export declare function getPackageInfo(name: string, currentVersion: string, direct: boolean, cutoff?: Date): Promise<DependencyInfo>;

package/dist/registry.js

@@ -0,0 +1,81 @@
+function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const na = pa[i] ?? 0;
+        const nb = pb[i] ?? 0;
+        if (na !== nb)
+            return na - nb;
+    }
+    return 0;
+}
+function findLatestBefore(time, versions, cutoff) {
+    let best;
+    for (const [version, dateStr] of Object.entries(time)) {
+        if (version === 'created' || version === 'modified')
+            continue;
+        if (version.includes('-'))
+            continue;
+        if (versions[version]?.deprecated)
+            continue;
+        const date = new Date(dateStr);
+        if (date <= cutoff && (!best || compareVersions(version, best) > 0)) {
+            best = version;
+        }
+    }
+    if (!best)
+        return undefined;
+    return { version: best, date: time[best] };
+}
+const registryCache = new Map();
+async function fetchRegistryData(name) {
+    const cached = registryCache.get(name);
+    if (cached)
+        return cached;
+    const url = `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+    const res = await fetch(url, {
+        headers: { Accept: 'application/json' },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch registry info for ${name}: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    registryCache.set(name, data);
+    return data;
+}
+export async function getPackageInfo(name, currentVersion, direct, cutoff) {
+    let data;
+    try {
+        data = await fetchRegistryData(name);
+    }
+    catch (err) {
+        console.error(`Warning: ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            name,
+            direct,
+            currentVersion,
+            currentVersionDate: '',
+            latestVersion: '',
+            latestVersionDate: '',
+        };
+    }
+    let latestVersion;
+    let latestVersionDate;
+    if (cutoff) {
+        const found = findLatestBefore(data.time, data.versions, cutoff);
+        latestVersion = found?.version ?? data['dist-tags'].latest;
+        latestVersionDate = found?.date ?? data.time[latestVersion] ?? 'unknown';
+    }
+    else {
+        latestVersion = data['dist-tags'].latest;
+        latestVersionDate = data.time[latestVersion] ?? 'unknown';
+    }
+    return {
+        name,
+        direct,
+        currentVersion,
+        currentVersionDate: data.time[currentVersion] ?? 'unknown',
+        latestVersion,
+        latestVersionDate,
+    };
+}

package/dist/summarize.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/summarize.js

@@ -0,0 +1,47 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { program } from "commander";
+const MS_PER_YEAR = 365.25 * 24 * 60 * 60 * 1000;
+function calculateLibyears(result) {
+    let total = 0;
+    for (const dep of result.dependencies) {
+        if (dep.currentVersionDate === "unknown" || dep.latestVersionDate === "unknown")
+            continue;
+        const current = new Date(dep.currentVersionDate).getTime();
+        const latest = new Date(dep.latestVersionDate).getTime();
+        const diff = latest - current;
+        if (diff > 0) {
+            total += diff / MS_PER_YEAR;
+        }
+    }
+    return total;
+}
+program
+    .name("depcollector-summarize")
+    .description("Summarize multiple depcollector JSON reports into a CSV")
+    .argument("<directory>", "Directory containing depcollector JSON files")
+    .parse();
+async function main() {
+    const dir = program.args[0];
+    const files = (await readdir(dir)).filter((f) => f.endsWith(".json")).sort();
+    const rows = [];
+    for (const file of files) {
+        const content = await readFile(join(dir, file), "utf-8");
+        const result = JSON.parse(content);
+        const libyears = calculateLibyears(result);
+        rows.push({
+            gitSha: result.gitSha,
+            gitTimestamp: result.gitTimestamp,
+            libyears: libyears.toFixed(2),
+        });
+    }
+    rows.sort((a, b) => a.gitTimestamp.localeCompare(b.gitTimestamp));
+    console.log("commit_sha,commit_timestamp,libyears");
+    for (const row of rows) {
+        console.log(`${row.gitSha},${row.gitTimestamp},${row.libyears}`);
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export interface LockedDependency {
+    name: string;
+    version: string;
+}
+export interface DependencyInfo {
+    name: string;
+    direct: boolean;
+    currentVersion: string;
+    currentVersionDate: string;
+    latestVersion: string;
+    latestVersionDate: string;
+}
+export interface CollectionResult {
+    ecosystem: 'npm';
+    projectName?: string;
+    manifestPath?: string;
+    collectedAt: string;
+    gitSha: string;
+    gitTimestamp: string;
+    dependencies: DependencyInfo[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@yob/depcollector",
+  "version": "0.1.0",
+  "description": "Collect dependency version and age information from package.json and package-lock.json",
+  "type": "module",
+  "bin": {
+    "depcollector": "./bin/depcollector.mjs"
+  },
+  "author": "James Healy (https://yob.id.au)",
+  "scripts": {
+    "build": "tsc",
+    "formatting": "prettier --check .",
+    "formatting:fix": "prettier --write .",
+    "prepublishOnly": "npm run build",
+    "start": "tsx src/index.ts"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "keywords": [
+    "dependencies",
+    "versions",
+    "audit",
+    "npm"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22",
+    "prettier": "^3.8.1",
+    "tsx": "^4",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  }
+}