@rainy-updates/cli 0.5.1 → 0.5.2-rc.1

package/dist/commands/snapshot/parser.d.ts

@@ -0,0 +1,2 @@
+import type { SnapshotOptions } from "../../types/index.js";
+export declare function parseSnapshotArgs(args: string[]): SnapshotOptions;

package/dist/commands/snapshot/parser.js

@@ -0,0 +1,80 @@
+const VALID_ACTIONS = ["save", "list", "restore", "diff"];
+export function parseSnapshotArgs(args) {
+    const options = {
+        cwd: process.cwd(),
+        workspace: false,
+        action: "list",
+        label: undefined,
+        snapshotId: undefined,
+        storeFile: undefined,
+    };
+    // First positional arg is the action
+    let positionalIndex = 0;
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const current = args[i];
+        const next = args[i + 1];
+        if (current === "--cwd" && next) {
+            options.cwd = next;
+            i++;
+            continue;
+        }
+        if (current === "--cwd")
+            throw new Error("Missing value for --cwd");
+        if (current === "--workspace") {
+            options.workspace = true;
+            continue;
+        }
+        if (current === "--label" && next) {
+            options.label = next;
+            i++;
+            continue;
+        }
+        if (current === "--label")
+            throw new Error("Missing value for --label");
+        if (current === "--store" && next) {
+            options.storeFile = next;
+            i++;
+            continue;
+        }
+        if (current === "--store")
+            throw new Error("Missing value for --store");
+        if (current === "--help" || current === "-h") {
+            process.stdout.write(SNAPSHOT_HELP);
+            process.exit(0);
+        }
+        if (current.startsWith("-"))
+            throw new Error(`Unknown option: ${current}`);
+        // Positional arguments
+        positionals.push(current);
+    }
+    // positionals[0] = action, positionals[1] = id/label for restore/diff
+    if (positionals.length >= 1) {
+        const action = positionals[0];
+        if (!VALID_ACTIONS.includes(action)) {
+            throw new Error(`Unknown snapshot action: "${positionals[0]}". Valid: ${VALID_ACTIONS.join(", ")}`);
+        }
+        options.action = action;
+    }
+    if (positionals.length >= 2) {
+        // For restore/diff the second positional is the id/label
+        options.snapshotId = positionals[1];
+    }
+    return options;
+}
+const SNAPSHOT_HELP = `
+rup snapshot — Save, list, restore, and diff dependency state snapshots
+
+Usage:
+  rup snapshot save [--label <name>]    Save current dependency state
+  rup snapshot list                     List all saved snapshots
+  rup snapshot restore <id|label>       Restore package.json files from a snapshot
+  rup snapshot diff <id|label>          Show changes since a snapshot
+
+Options:
+  --label <name>        Human-readable label for the snapshot
+  --store <path>        Custom snapshot store file (default: .rup-snapshots.json)
+  --workspace           Include all workspace packages
+  --cwd <path>          Working directory (default: cwd)
+  --help                Show this help
+`.trimStart();

package/dist/commands/snapshot/runner.d.ts

@@ -0,0 +1,11 @@
+import type { SnapshotOptions, SnapshotResult } from "../../types/index.js";
+/**
+ * Entry point for `rup snapshot`. Lazy-loaded by cli.ts.
+ *
+ * Actions:
+ *   save     — Capture package.json + lockfile state → store
+ *   list     — Print all saved snapshots
+ *   restore  — Restore a snapshot by id or label
+ *   diff     — Show dependency changes since a snapshot
+ */
+export declare function runSnapshot(options: SnapshotOptions): Promise<SnapshotResult>;

package/dist/commands/snapshot/runner.js

@@ -0,0 +1,115 @@
+import process from "node:process";
+import { discoverPackageDirs } from "../../workspace/discover.js";
+import { SnapshotStore, captureState, restoreState, diffManifests, } from "./store.js";
+/**
+ * Entry point for `rup snapshot`. Lazy-loaded by cli.ts.
+ *
+ * Actions:
+ *   save     — Capture package.json + lockfile state → store
+ *   list     — Print all saved snapshots
+ *   restore  — Restore a snapshot by id or label
+ *   diff     — Show dependency changes since a snapshot
+ */
+export async function runSnapshot(options) {
+    const result = {
+        action: options.action,
+        errors: [],
+        warnings: [],
+    };
+    const packageDirs = await discoverPackageDirs(options.cwd, options.workspace);
+    const store = new SnapshotStore(options.cwd, options.storeFile);
+    switch (options.action) {
+        // ─ save ──────────────────────────────────────────────────────────────────
+        case "save": {
+            const label = options.label ??
+                `snap-${new Date().toISOString().replace(/[:T]/g, "-").slice(0, 19)}`;
+            const { manifests, lockfileHashes } = await captureState(packageDirs);
+            const entry = await store.saveSnapshot(manifests, lockfileHashes, label);
+            result.snapshotId = entry.id;
+            result.label = entry.label;
+            process.stdout.write(`✔ Snapshot saved: ${entry.label} (${entry.id})\n`);
+            break;
+        }
+        // ─ list ──────────────────────────────────────────────────────────────────
+        case "list": {
+            const entries = await store.listSnapshots();
+            result.entries = entries.map((e) => ({
+                id: e.id,
+                label: e.label,
+                createdAt: new Date(e.createdAt).toISOString(),
+            }));
+            if (entries.length === 0) {
+                process.stdout.write("No snapshots saved yet. Use `rup snapshot save` to create one.\n");
+            }
+            else {
+                process.stdout.write(`\n${entries.length} snapshot(s):\n\n`);
+                process.stdout.write("  " + "ID".padEnd(30) + "Label".padEnd(30) + "Created\n");
+                process.stdout.write("  " + "─".repeat(75) + "\n");
+                for (const e of entries) {
+                    process.stdout.write("  " +
+                        e.id.padEnd(30) +
+                        e.label.padEnd(30) +
+                        new Date(e.createdAt).toLocaleString() +
+                        "\n");
+                }
+                process.stdout.write("\n");
+            }
+            break;
+        }
+        // ─ restore ───────────────────────────────────────────────────────────────
+        case "restore": {
+            const idOrLabel = options.snapshotId ?? options.label;
+            if (!idOrLabel) {
+                result.errors.push("Restore requires a snapshot ID or label. Usage: rup snapshot restore <id|label>");
+                break;
+            }
+            const entry = await store.findSnapshot(idOrLabel);
+            if (!entry) {
+                result.errors.push(`Snapshot not found: ${idOrLabel}. Use \`rup snapshot list\` to view saved snapshots.`);
+                break;
+            }
+            await restoreState(entry);
+            result.snapshotId = entry.id;
+            result.label = entry.label;
+            const count = Object.keys(entry.manifests).length;
+            process.stdout.write(`✔ Restored ${count} package.json file(s) from snapshot "${entry.label}" (${entry.id})\n`);
+            process.stdout.write("  Re-run your package manager install to apply.\n");
+            break;
+        }
+        // ─ diff ──────────────────────────────────────────────────────────────────
+        case "diff": {
+            const idOrLabel = options.snapshotId ?? options.label;
+            if (!idOrLabel) {
+                result.errors.push("Diff requires a snapshot ID or label. Usage: rup snapshot diff <id|label>");
+                break;
+            }
+            const entry = await store.findSnapshot(idOrLabel);
+            if (!entry) {
+                result.errors.push(`Snapshot not found: ${idOrLabel}`);
+                break;
+            }
+            const { manifests: currentManifests } = await captureState(packageDirs);
+            const changes = diffManifests(entry.manifests, currentManifests);
+            result.diff = changes;
+            if (changes.length === 0) {
+                process.stdout.write(`✔ No dependency changes since snapshot "${entry.label}"\n`);
+            }
+            else {
+                process.stdout.write(`\nDependency changes since snapshot "${entry.label}":\n\n`);
+                process.stdout.write("  " + "Package".padEnd(35) + "Before".padEnd(20) + "After\n");
+                process.stdout.write("  " + "─".repeat(65) + "\n");
+                for (const c of changes) {
+                    process.stdout.write("  " + c.name.padEnd(35) + c.from.padEnd(20) + c.to + "\n");
+                }
+                process.stdout.write("\n");
+            }
+            break;
+        }
+    }
+    if (result.errors.length > 0) {
+        for (const err of result.errors) {
+            process.stderr.write(`[snapshot] ✖ ${err}\n`);
+        }
+    }
+    return result;
+}

package/dist/commands/snapshot/store.d.ts

@@ -0,0 +1,35 @@
+import type { SnapshotEntry } from "../../types/index.js";
+/**
+ * Lightweight SQLite-free snapshot store (uses a JSON file in the project root).
+ *
+ * Design goals:
+ *   - No extra runtime dependencies (SQLite bindings vary by runtime)
+ *   - Human-readable store file (git-committable if desired)
+ *   - Atomic writes via tmp-rename to prevent corruption
+ *   - Fast: entire store fits in memory for typical use (< 50 snapshots)
+ */
+export declare class SnapshotStore {
+    private readonly storePath;
+    private entries;
+    private loaded;
+    constructor(cwd: string, storeFile?: string);
+    load(): Promise<void>;
+    save(): Promise<void>;
+    saveSnapshot(manifests: Record<string, string>, lockfileHashes: Record<string, string>, label: string): Promise<SnapshotEntry>;
+    listSnapshots(): Promise<SnapshotEntry[]>;
+    findSnapshot(idOrLabel: string): Promise<SnapshotEntry | null>;
+    deleteSnapshot(idOrLabel: string): Promise<boolean>;
+}
+/** Captures current package.json and lockfile state for a set of directories. */
+export declare function captureState(packageDirs: string[]): Promise<{
+    manifests: Record<string, string>;
+    lockfileHashes: Record<string, string>;
+}>;
+/** Restores package.json files from a snapshot's manifest map. */
+export declare function restoreState(entry: SnapshotEntry): Promise<void>;
+/** Computes a diff of dependency versions between two manifest snapshots. */
+export declare function diffManifests(before: Record<string, string>, after: Record<string, string>): Array<{
+    name: string;
+    from: string;
+    to: string;
+}>;

package/dist/commands/snapshot/store.js

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const DEFAULT_STORE_NAME = ".rup-snapshots.json";
+/**
+ * Lightweight SQLite-free snapshot store (uses a JSON file in the project root).
+ *
+ * Design goals:
+ *   - No extra runtime dependencies (SQLite bindings vary by runtime)
+ *   - Human-readable store file (git-committable if desired)
+ *   - Atomic writes via tmp-rename to prevent corruption
+ *   - Fast: entire store fits in memory for typical use (< 50 snapshots)
+ */
+export class SnapshotStore {
+    storePath;
+    entries = [];
+    loaded = false;
+    constructor(cwd, storeFile) {
+        this.storePath = storeFile
+            ? path.isAbsolute(storeFile)
+                ? storeFile
+                : path.join(cwd, storeFile)
+            : path.join(cwd, DEFAULT_STORE_NAME);
+    }
+    async load() {
+        if (this.loaded)
+            return;
+        try {
+            const raw = await fs.readFile(this.storePath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                this.entries = parsed;
+            }
+        }
+        catch {
+            this.entries = [];
+        }
+        this.loaded = true;
+    }
+    async save() {
+        const tmp = this.storePath + ".tmp";
+        await fs.writeFile(tmp, JSON.stringify(this.entries, null, 2) + "\n", "utf8");
+        await fs.rename(tmp, this.storePath);
+    }
+    async saveSnapshot(manifests, lockfileHashes, label) {
+        await this.load();
+        const id = `snap-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+        const entry = {
+            id,
+            label,
+            createdAt: Date.now(),
+            manifests,
+            lockfileHashes,
+        };
+        this.entries.push(entry);
+        await this.save();
+        return entry;
+    }
+    async listSnapshots() {
+        await this.load();
+        return [...this.entries].sort((a, b) => b.createdAt - a.createdAt);
+    }
+    async findSnapshot(idOrLabel) {
+        await this.load();
+        return (this.entries.find((e) => e.id === idOrLabel || e.label === idOrLabel) ??
+            null);
+    }
+    async deleteSnapshot(idOrLabel) {
+        await this.load();
+        const before = this.entries.length;
+        this.entries = this.entries.filter((e) => e.id !== idOrLabel && e.label !== idOrLabel);
+        if (this.entries.length < before) {
+            await this.save();
+            return true;
+        }
+        return false;
+    }
+}
+/** Captures current package.json and lockfile state for a set of directories. */
+export async function captureState(packageDirs) {
+    const manifests = {};
+    const lockfileHashes = {};
+    const LOCKFILES = [
+        "package-lock.json",
+        "pnpm-lock.yaml",
+        "yarn.lock",
+        "bun.lockb",
+    ];
+    await Promise.all(packageDirs.map(async (dir) => {
+        // Read package.json
+        try {
+            const content = await fs.readFile(path.join(dir, "package.json"), "utf8");
+            manifests[dir] = content;
+        }
+        catch {
+            // No package.json — skip
+        }
+        // Hash the first lockfile found
+        for (const lf of LOCKFILES) {
+            try {
+                const content = await fs.readFile(path.join(dir, lf));
+                lockfileHashes[dir] = createHash("sha256")
+                    .update(content)
+                    .digest("hex");
+                break;
+            }
+            catch {
+                // Try next
+            }
+        }
+    }));
+    return { manifests, lockfileHashes };
+}
+/** Restores package.json files from a snapshot's manifest map. */
+export async function restoreState(entry) {
+    await Promise.all(Object.entries(entry.manifests).map(async ([dir, content]) => {
+        const manifestPath = path.join(dir, "package.json");
+        const tmp = manifestPath + ".tmp";
+        await fs.writeFile(tmp, content, "utf8");
+        await fs.rename(tmp, manifestPath);
+    }));
+}
+/** Computes a diff of dependency versions between two manifest snapshots. */
+export function diffManifests(before, after) {
+    const changes = [];
+    for (const [dir, afterJson] of Object.entries(after)) {
+        const beforeJson = before[dir];
+        if (!beforeJson)
+            continue;
+        let beforeManifest;
+        let afterManifest;
+        try {
+            beforeManifest = JSON.parse(beforeJson);
+            afterManifest = JSON.parse(afterJson);
+        }
+        catch {
+            continue;
+        }
+        const fields = [
+            "dependencies",
+            "devDependencies",
+            "optionalDependencies",
+        ];
+        for (const field of fields) {
+            const before = beforeManifest[field] ?? {};
+            const after = afterManifest[field] ?? {};
+            const allNames = new Set([...Object.keys(before), ...Object.keys(after)]);
+            for (const name of allNames) {
+                const fromVer = before[name] ?? "(removed)";
+                const toVer = after[name] ?? "(removed)";
+                if (fromVer !== toVer) {
+                    changes.push({ name, from: fromVer, to: toVer });
+                }
+            }
+        }
+    }
+    return changes;
+}

package/dist/commands/unused/matcher.d.ts

@@ -0,0 +1,22 @@
+import type { PackageManifest } from "../../types/index.js";
+import type { UnusedDependency } from "../../types/index.js";
+/**
+ * Cross-references declared package.json dependencies against imported package names
+ * to surface two classes of problems:
+ *
+ *   - "declared-not-imported": in package.json but never imported in source
+ *   - "imported-not-declared": imported in source but absent from package.json
+ */
+export interface MatchOptions {
+    includeDevDependencies: boolean;
+}
+export declare function matchDependencies(manifest: PackageManifest, importedPackages: Set<string>, packageDir: string, options: MatchOptions): {
+    unused: UnusedDependency[];
+    missing: UnusedDependency[];
+};
+/**
+ * Applies the unused/missing result of `matchDependencies` to a package.json
+ * manifest in-memory, removing `unused` entries. Returns the modified manifest
+ * as a formatted JSON string ready to write back to disk.
+ */
+export declare function removeUnusedFromManifest(manifestJson: string, unused: UnusedDependency[]): string;

package/dist/commands/unused/matcher.js

@@ -0,0 +1,95 @@
+export function matchDependencies(manifest, importedPackages, packageDir, options) {
+    const declared = buildDeclaredMap(manifest, options);
+    const unused = [];
+    const missing = [];
+    // Find declared deps not seen in source imports
+    for (const [name, field] of declared) {
+        if (!importedPackages.has(name)) {
+            unused.push({
+                name,
+                kind: "declared-not-imported",
+                declaredIn: field,
+            });
+        }
+    }
+    // Find imports not declared in package.json
+    for (const importedName of importedPackages) {
+        if (!declared.has(importedName)) {
+            missing.push({
+                name: importedName,
+                kind: "imported-not-declared",
+                importedFrom: packageDir,
+            });
+        }
+    }
+    return { unused, missing };
+}
+/**
+ * Build a map of { packageName → fieldName } from package.json.
+ * Only includes the fields requested (e.g. skip devDependencies when
+ * includeDevDependencies is false).
+ */
+function buildDeclaredMap(manifest, options) {
+    const result = new Map();
+    const fields = [
+        [
+            manifest.dependencies,
+            "dependencies",
+        ],
+        [
+            manifest.optionalDependencies,
+            "optionalDependencies",
+        ],
+    ];
+    if (options.includeDevDependencies) {
+        fields.push([
+            manifest.devDependencies,
+            "devDependencies",
+        ]);
+    }
+    // peerDependencies are intentionally excluded — they are rarely directly imported
+    // and are a separate concern handled by `rup resolve`.
+    for (const [deps, fieldName] of fields) {
+        if (!deps)
+            continue;
+        for (const name of Object.keys(deps)) {
+            if (!result.has(name)) {
+                result.set(name, fieldName);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Applies the unused/missing result of `matchDependencies` to a package.json
+ * manifest in-memory, removing `unused` entries. Returns the modified manifest
+ * as a formatted JSON string ready to write back to disk.
+ */
+export function removeUnusedFromManifest(manifestJson, unused) {
+    if (unused.length === 0)
+        return manifestJson;
+    let parsed;
+    try {
+        parsed = JSON.parse(manifestJson);
+    }
+    catch {
+        return manifestJson;
+    }
+    const unusedNames = new Set(unused.map((u) => u.name));
+    const fields = [
+        "dependencies",
+        "devDependencies",
+        "optionalDependencies",
+    ];
+    for (const field of fields) {
+        const deps = parsed[field];
+        if (!deps || typeof deps !== "object")
+            continue;
+        for (const name of Object.keys(deps)) {
+            if (unusedNames.has(name)) {
+                delete deps[name];
+            }
+        }
+    }
+    return JSON.stringify(parsed, null, 2) + "\n";
+}

package/dist/commands/unused/parser.d.ts

@@ -0,0 +1,2 @@
+import type { UnusedOptions } from "../../types/index.js";
+export declare function parseUnusedArgs(args: string[]): UnusedOptions;

package/dist/commands/unused/parser.js

@@ -0,0 +1,95 @@
+const DEFAULT_SRC_DIRS = ["src"];
+export function parseUnusedArgs(args) {
+    const options = {
+        cwd: process.cwd(),
+        workspace: false,
+        srcDirs: DEFAULT_SRC_DIRS,
+        includeDevDependencies: true,
+        fix: false,
+        dryRun: false,
+        jsonFile: undefined,
+        concurrency: 16,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const current = args[i];
+        const next = args[i + 1];
+        if (current === "--cwd" && next) {
+            options.cwd = next;
+            i++;
+            continue;
+        }
+        if (current === "--cwd")
+            throw new Error("Missing value for --cwd");
+        if (current === "--workspace") {
+            options.workspace = true;
+            continue;
+        }
+        if (current === "--src" && next) {
+            options.srcDirs = next
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean);
+            i++;
+            continue;
+        }
+        if (current === "--src")
+            throw new Error("Missing value for --src");
+        if (current === "--no-dev") {
+            options.includeDevDependencies = false;
+            continue;
+        }
+        if (current === "--fix") {
+            options.fix = true;
+            continue;
+        }
+        if (current === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (current === "--json-file" && next) {
+            options.jsonFile = next;
+            i++;
+            continue;
+        }
+        if (current === "--json-file")
+            throw new Error("Missing value for --json-file");
+        if (current === "--concurrency" && next) {
+            const parsed = Number(next);
+            if (!Number.isInteger(parsed) || parsed <= 0)
+                throw new Error("--concurrency must be a positive integer");
+            options.concurrency = parsed;
+            i++;
+            continue;
+        }
+        if (current === "--concurrency")
+            throw new Error("Missing value for --concurrency");
+        if (current === "--help" || current === "-h") {
+            process.stdout.write(UNUSED_HELP);
+            process.exit(0);
+        }
+        if (current.startsWith("-"))
+            throw new Error(`Unknown option: ${current}`);
+    }
+    return options;
+}
+const UNUSED_HELP = `
+rup unused — Detect unused and missing npm dependencies
+
+Usage:
+  rup unused [options]
+
+Options:
+  --src <dirs>          Comma-separated source directories to scan (default: src)
+  --workspace           Scan all workspace packages
+  --no-dev              Exclude devDependencies from unused detection
+  --fix                 Remove unused dependencies from package.json
+  --dry-run             Preview changes without writing
+  --json-file <path>    Write JSON report to file
+  --cwd <path>          Working directory (default: cwd)
+  --concurrency <n>     Parallel file scanning concurrency (default: 16)
+  --help                Show this help
+
+Exit codes:
+  0  No unused dependencies found
+  1  Unused or missing dependencies detected
+`.trimStart();

package/dist/commands/unused/runner.d.ts

@@ -0,0 +1,11 @@
+import type { UnusedOptions, UnusedResult } from "../../types/index.js";
+/**
+ * Entry point for `rup unused`. Lazy-loaded by cli.ts.
+ *
+ * Strategy:
+ *   1. Collect all source directories to scan
+ *   2. Scan them in parallel for imported package names
+ *   3. Cross-reference against package.json declarations
+ *   4. Optionally apply --fix (remove unused from package.json)
+ */
+export declare function runUnused(options: UnusedOptions): Promise<UnusedResult>;