jpm-pkg 1.0.3

package/src/core/lockfile.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const path = require('node:path');
+const { readJSONSafe, writeJSON } = require('../utils/fs');
+const { hashString } = require('../security/integrity');
+
+const LOCK_VERSION = 1;
+const LOCK_FILE = 'jpm-lock.json';
+
+/**
+ * jpm-lock.json structure:
+ * {
+ *   "lockVersion": 1,
+ *   "packages": {
+ *     "express@4.18.2": {
+ *       "name": "express",
+ *       "version": "4.18.2",
+ *       "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
+ *       "integrity": "sha512-...",
+ *       "dependencies": { "accepts": "^1.3.8", ... }
+ *     },
+ *     ...
+ *   }
+ * }
+ */
+
+class Lockfile {
+    constructor(projectRoot) {
+        this.filePath = path.join(projectRoot, LOCK_FILE);
+        this._data = this._load();
+    }
+
+    _load() {
+        const data = readJSONSafe(this.filePath, null);
+        if (!data) return { lockVersion: LOCK_VERSION, packages: {} };
+        return data;
+    }
+
+    /**
+     * Build/update lock file from a resolved package map
+     */
+    update(resolvedMap) {
+        const packages = {};
+        const keys = Array.from(resolvedMap.keys()).sort();
+        for (const key of keys) {
+            const meta = resolvedMap.get(key);
+            packages[key] = {
+                name: meta.name,
+                version: meta.version,
+                resolved: meta.resolved || '',
+                integrity: meta.integrity || '',
+                shasum: meta.shasum || '',
+                dependencies: meta.deps || {},
+                engines: meta.engines || {},
+            };
+        }
+
+        const integrity = hashString(JSON.stringify(packages));
+        this._data = {
+            lockVersion: LOCK_VERSION,
+            integrity,
+            packages
+        };
+        return this;
+    }
+
+    /**
+     * Verifies if the lockfile has been tampered with.
+     */
+    verify() {
+        if (!this._data.integrity || !this._data.packages) return true;
+        const actual = hashString(JSON.stringify(this._data.packages));
+        return actual === this._data.integrity;
+    }
+
+    /** Add or update a single package entry */
+    setPackage(name, version, meta) {
+        const key = `${name}@${version}`;
+        this._data.packages[key] = {
+            name,
+            version,
+            resolved: meta.resolved || '',
+            integrity: meta.integrity || '',
+            shasum: meta.shasum || '',
+            dependencies: meta.dependencies || {},
+        };
+        return this;
+    }
+
+    /** Remove a package entry */
+    removePackage(name, version) {
+        const key = `${name}@${version}`;
+        delete this._data.packages[key];
+        return this;
+    }
+
+    /** Look up a specific package in the lock file */
+    getPackage(name, version) {
+        return this._data.packages[`${name}@${version}`] || null;
+    }
+
+    /** Check whether the lock file has a resolved entry for name@range */
+    hasPackage(name, version) {
+        return Boolean(this._data.packages[`${name}@${version}`]);
+    }
+
+    /** Return all locked packages as array */
+    allPackages() {
+        return Object.values(this._data.packages);
+    }
+
+    /** Write lock file to disk */
+    save() {
+        writeJSON(this.filePath, this._data, 2);
+        return this;
+    }
+
+    /** Raw data */
+    get data() { return this._data; }
+
+    /** Whether a lock file exists */
+    exists() {
+        const fs = require('node:fs');
+        return fs.existsSync(this.filePath);
+    }
+}
+
+module.exports = Lockfile;

package/src/core/package-json.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { readJSONSafe, writeJSON, findPackageJson } = require('../utils/fs');
+const logger = require('../utils/logger');
+
+const REQUIRED_FIELDS = ['name', 'version'];
+
+class PackageJSON {
+    constructor(filePath) {
+        this.filePath = filePath;
+        this._data = this._load();
+    }
+
+    static fromDir(dir) {
+        const f = path.join(dir, 'package.json');
+        return new PackageJSON(f);
+    }
+
+    static find(startDir = process.cwd()) {
+        const f = findPackageJson(startDir);
+        if (!f) throw new Error('No package.json found in this directory or any parent.');
+        return new PackageJSON(f);
+    }
+
+    _load() {
+        const data = readJSONSafe(this.filePath, null);
+        if (!data) return this._empty();
+        return data;
+    }
+
+    _empty() {
+        return {
+            name: path.basename(path.dirname(this.filePath || process.cwd())),
+            version: '1.0.0',
+            description: '',
+            main: 'index.js',
+            scripts: { test: 'echo "Error: no test specified" && exit 1' },
+            keywords: [],
+            author: '',
+            license: 'MIT',
+            dependencies: {},
+            devDependencies: {},
+        };
+    }
+
+    // ── Accessors ────────────────────────────────────────────────────────────────
+
+    get name() { return this._data.name; }
+    get version() { return this._data.version; }
+    get dependencies() { return this._data.dependencies || {}; }
+    get devDependencies() { return this._data.devDependencies || {}; }
+    get peerDependencies() { return this._data.peerDependencies || {}; }
+    get optionalDeps() { return this._data.optionalDependencies || {}; }
+    get scripts() { return this._data.scripts || {}; }
+    get workspaces() { return this._data.workspaces || []; }
+    get main() { return this._data.main || 'index.js'; }
+    get bin() { return this._data.bin || {}; }
+    get engines() { return this._data.engines || {}; }
+    get data() { return this._data; }
+    get dir() { return path.dirname(this.filePath); }
+
+    // ── Mutations ────────────────────────────────────────────────────────────────
+
+    addDependency(name, version, { dev = false, exact = false } = {}) {
+        const range = exact ? version : `^${version}`;
+        const key = dev ? 'devDependencies' : 'dependencies';
+        if (!this._data[key]) this._data[key] = {};
+        this._data[key][name] = range;
+        return this;
+    }
+
+    removeDependency(name) {
+        for (const key of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+            if (this._data[key]) delete this._data[key][name];
+        }
+        return this;
+    }
+
+    setField(key, value) {
+        this._data[key] = value;
+        return this;
+    }
+
+    setVersion(version) {
+        this._data.version = version;
+        return this;
+    }
+
+    addScript(name, command) {
+        if (!this._data.scripts) this._data.scripts = {};
+        this._data.scripts[name] = command;
+        return this;
+    }
+
+    // ── Validation ────────────────────────────────────────────────────────────────
+
+    validate() {
+        const errors = [];
+        for (const field of REQUIRED_FIELDS) {
+            if (!this._data[field]) errors.push(`Missing required field: "${field}"`);
+        }
+        if (this._data.name && !/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(this._data.name)) {
+            errors.push(`Invalid package name: "${this._data.name}"`);
+        }
+        if (this._data.version && !/^\d+\.\d+\.\d+/.test(this._data.version)) {
+            errors.push(`Invalid version: "${this._data.version}"`);
+        }
+        return errors;
+    }
+
+    // ── Persistence ──────────────────────────────────────────────────────────────
+
+    save() {
+        writeJSON(this.filePath, this._data, 2);
+        return this;
+    }
+
+    exists() {
+        return fs.existsSync(this.filePath);
+    }
+
+    allDeps() {
+        return {
+            ...this.dependencies,
+            ...this.devDependencies,
+            ...this.optionalDeps,
+        };
+    }
+}
+
+module.exports = PackageJSON;

package/src/core/registry.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const { getJSON, download } = require('../utils/http');
+const config = require('../utils/config');
+const logger = require('../utils/logger');
+
+const REGISTRY = () => config.registry.replace(/\/$/, '');
+
+const LRUCache = require('../utils/lru-cache');
+const env = require('../utils/env');
+
+/**
+ * In-memory metadata cache for registry requests, optimized for resolution speed.
+ * @type {LRUCache}
+ * @private
+ */
+const metaCache = new LRUCache(1000);
+
+/**
+ * Fetches the full packument for a package from the registry.
+ * 
+ * @param {string} name - The canonical name of the package
+ * @returns {Promise<Object>} The packument object containing version history and tags
+ */
+async function getPackument(name) {
+    const url = `${REGISTRY()}/${encodeURIComponent(name).replace('%40', '@')}`;
+    if (metaCache.has(url)) return metaCache.get(url);
+
+    logger.verbose(`registry GET ${url}`);
+    const doc = await getJSON(url, {
+        headers: { Accept: 'application/vnd.npm.install-v1+json, application/json' },
+        timeout: config.timeout,
+        retries: config.retries,
+    });
+    metaCache.set(url, doc);
+    return doc;
+}
+
+/**
+ * Fetches specific version metadata for a package.
+ * 
+ * @param {string} name - The package name
+ * @param {string} version - Specific version or dist-tag (e.g., 'latest')
+ * @returns {Promise<Object>} The version manifest
+ * @throws {Error} If the requested version is unavailable in the registry
+ */
+async function getVersion(name, version) {
+    const packument = await getPackument(name);
+    const ver = version === 'latest'
+        ? packument['dist-tags']?.latest
+        : version;
+
+    const data = packument.versions?.[ver];
+    if (!data) throw new Error(`Version ${name}@${ver} not found in registry`);
+    return data;
+}
+
+/**
+ * Retrieves all available version strings for a package.
+ * 
+ * @param {string} name - The package name
+ * @returns {Promise<string[]>} Array of version strings
+ */
+async function getVersions(name) {
+    const packument = await getPackument(name);
+    return Object.keys(packument.versions || {});
+}
+
+/**
+ * Retrieves the version string flagged as 'latest' in the registry.
+ * 
+ * @param {string} name - The package name
+ * @returns {Promise<string|undefined>} The latest version string
+ */
+async function getLatest(name) {
+    const packument = await getPackument(name);
+    return packument['dist-tags']?.latest;
+}
+
+/**
+ * Retrieves all distribution tags associated with a package.
+ * 
+ * @param {string} name - The package name
+ * @returns {Promise<Object.<string, string>>} Map of tags to versions
+ */
+async function getDistTags(name) {
+    const packument = await getPackument(name);
+    return packument['dist-tags'] || {};
+}
+
+/**
+ * Downloads a package tarball and writes it to a destination stream.
+ * 
+ * @param {string} tarballUrl - Fully qualified URL to the tarball
+ * @param {import('node:stream').Writable} destStream - Target writable stream
+ * @param {Function} [onProgress] - Optional heartbeat for download progress
+ * @returns {Promise<void>}
+ */
+async function downloadTarball(tarballUrl, destStream, onProgress) {
+    logger.verbose(`tarball GET ${tarballUrl}`);
+    return download(tarballUrl, destStream, {
+        timeout: config.timeout * 2,
+        retries: config.retries,
+        onProgress,
+    });
+}
+
+/**
+ * Executes a full-text search against the npm registry.
+ * 
+ * @param {string} query - Search term
+ * @param {Object} [options] - Pagination options
+ * @param {number} [options.size=20] - Number of results to return
+ * @param {number} [options.from=0] - Offset for results
+ * @returns {Promise<Object[]>} List of search result objects
+ */
+async function search(query, { size = 20, from = 0 } = {}) {
+    const url = `${REGISTRY()}/-/v1/search?text=${encodeURIComponent(query)}&size=${size}&from=${from}`;
+    const doc = await getJSON(url, { timeout: config.timeout });
+    return doc.objects || [];
+}
+
+/**
+ * Queries the registry for known security vulnerabilities.
+ * 
+ * @param {Object.<string, string[]>} requires - Map of package names to lists of required versions
+ * @returns {Promise<Object>} Audit report containing vulnerabilities and metadata
+ */
+async function fetchAdvisories(requires) {
+    const url = `https://registry.npmjs.org/-/npm/v1/security/audits/quick`;
+    const packages = {};
+    for (const [name, versions] of Object.entries(requires)) {
+        packages[name] = versions;
+    }
+
+    const { request } = require('../utils/http');
+    const body = JSON.stringify({
+        name: 'audit-target',
+        version: '1.0.0',
+        requires: Object.fromEntries(
+            Object.entries(requires).map(([n, vs]) => [n, vs[0] || '*'])
+        ),
+        dependencies: packages,
+    });
+
+    const res = await request(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(body),
+        },
+        body,
+        timeout: 30_000,
+        retries: 2,
+        strict: true, // Security: Always use HTTPS for audits
+    });
+
+    try { return JSON.parse(res.body); }
+    catch { return { advisories: {}, metadata: {} }; }
+}
+
+module.exports = {
+    getPackument, getVersion, getVersions,
+    getLatest, getDistTags,
+    downloadTarball, search, fetchAdvisories,
+};

package/src/core/resolver.js

@@ -0,0 +1,248 @@
+'use strict';
+
+const registry = require('./registry');
+const semver = require('../utils/semver');
+const system = require('../utils/system');
+const logger = require('../utils/logger');
+
+/**
+ * Resolves a full dependency tree given a root package.json dependencies map.
+ *
+ * Returns a flat map: { "name@version" => { name, version, resolved, integrity, dependencies } }
+ * Also detects circular dependencies and performs basic deduplication / hoisting.
+ */
+class Resolver {
+    /**
+     * Creates an instance of the Resolver.
+     * Initializes maps for resolved packages, in-flight requests, and the circular dependency stack.
+     */
+    constructor() {
+        /** @type {Map<string, object>} Map of "name@version" to package metadata */
+        this._resolved = new Map();
+        /** @type {Map<string, Promise>} Map of "name@range" to active resolution promises */
+        this._inFlight = new Map();
+        /** @type {string[]} Stack of package names being resolved to detect cycles */
+        this._stack = [];
+    }
+
+    /**
+     * Resolves a set of dependencies recursively.
+     * 
+     * @param {Object.<string, string>} [deps={}] - Regular dependencies (name to semver range)
+     * @param {Object.<string, string>} [devDeps={}] - Development dependencies
+     * @param {Object.<string, string>} [peerDeps={}] - Peer dependencies
+     * @returns {Promise<Map<string, object>>} A promise that resolves to the flat map of resolved packages
+     */
+    async resolve(deps = {}, devDeps = {}, peerDeps = {}, onProgress) {
+        const all = { ...deps, ...devDeps };
+        this._totalToResolve = Object.keys(all).length;
+        this._resolvedCount = 0;
+        this._onProgress = onProgress;
+
+        await Promise.all(
+            Object.entries(all).map(([name, range]) => this._resolveOne(name, range))
+        );
+        return this._resolved;
+    }
+
+    async _resolveOne(name, range) {
+        const key = `${name}@${range}`;
+
+        // Already in flight? Await the existing promise.
+        if (this._inFlight.has(key)) {
+            return this._inFlight.get(key);
+        }
+
+        // Create a new resolution promise and store it in _inFlight.
+        const p = this._doResolve(name, range);
+        this._inFlight.set(key, p);
+
+        try {
+            await p;
+            this._resolvedCount++;
+            this._onProgress?.(this._resolvedCount, this._totalToResolve);
+            return p;
+        } finally {
+            // No longer in flight once the promise settles.
+            this._inFlight.delete(key);
+        }
+    }
+
+    /**
+     * Internal resolution logic for a single package and range.
+     * 
+     * @param {string} name - The name of the package as declared in dependencies
+     * @param {string} range - The semver range or npm:alias
+     * @protected
+     */
+    async _doResolve(name, range) {
+        // Handle npm: alias protocol (e.g., "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0")
+        let targetName = name;
+        let targetRange = range === '' || range === '*' || range === 'latest' ? 'latest' : range;
+
+        if (targetRange.startsWith('npm:')) {
+            const parts = targetRange.slice(4).split('@');
+            // Handle scoped packages in alias: npm:@scope/pkg@range
+            if (targetRange.slice(4).startsWith('@')) {
+                targetName = '@' + parts[1];
+                targetRange = parts[2] || 'latest';
+            } else {
+                targetName = parts[0];
+                targetRange = parts[1] || 'latest';
+            }
+        }
+
+        try {
+            // 1. Fetch available versions for the target package
+            const versions = await registry.getVersions(targetName);
+
+            // 2. Select the best matching version candidates
+            const chosen = targetRange === 'latest'
+                ? await registry.getLatest(targetName)
+                : semver.maxSatisfying(versions, targetRange);
+
+            if (!chosen) {
+                throw new Error(`No version of ${targetName} satisfies "${targetRange}". Available: ${versions.slice(-5).join(', ')}`);
+            }
+
+            // The resolved key uses the original dependency name to allow multiple aliases of the same package
+            const resolvedKey = `${name}@${chosen}`;
+
+            // Check if already resolved to avoid redundant work
+            if (this._resolved.has(resolvedKey)) return;
+
+            // Detect circular dependencies on the current resolution path
+            if (this._stack.includes(resolvedKey)) return;
+
+            // 3. Retrieve exhaustive version metadata
+            const meta = await registry.getVersion(targetName, chosen);
+
+            // 4. Map metadata to internal representation
+            const metaToStore = {
+                name: targetName, // The actual package name for installation
+                alias: name !== targetName ? name : undefined, // Alias used in package.json
+                version: chosen,
+                resolved: meta.dist?.tarball,
+                integrity: meta.dist?.integrity || meta.dist?.shasum,
+                shasum: meta.dist?.shasum,
+                deps: meta.dependencies || {},
+                devDeps: meta.devDependencies || {},
+                peerDeps: meta.peerDependencies || {},
+                optDeps: meta.optionalDependencies || {},
+                engines: meta.engines || {},
+                bin: meta.bin || {},
+                scripts: meta.scripts || {},
+            };
+            this._resolved.set(resolvedKey, metaToStore);
+
+            // 5. Recursively resolve transitive dependencies
+            this._stack.push(resolvedKey);
+
+            // Combine normal and optional dependencies for resolution
+            const dependencies = {
+                ...metaToStore.deps,
+                ...metaToStore.optDeps
+            };
+
+            await Promise.all(
+                Object.entries(dependencies).map(async ([depName, depRange]) => {
+                    // Check if it's an optional dependency and if it's compatible with current system
+                    if (metaToStore.optDeps[depName]) {
+                        try {
+                            // We need the packument to see the OS/CPU of the potential version
+                            // Actually, a better way is to resolve it first, then check compatibility
+                            // before resolving its own transitive dependencies.
+                            // But to be even faster, we can check the packument's version metadata.
+                            const packument = await registry.getPackument(depName);
+                            const version = semver.maxSatisfying(Object.keys(packument.versions || {}), depRange);
+                            if (version) {
+                                const depMeta = packument.versions[version];
+                                if (depMeta && !system.isCompatible(depMeta)) {
+                                    logger.debug(`Skipping optional dependency ${depName}@${version}: incompatible platform`);
+                                    return;
+                                }
+                            }
+                        } catch (e) {
+                            // If packument fetch fails, we'll let _resolveOne handle it normally
+                        }
+                    }
+                    return this._resolveOne(depName, depRange);
+                })
+            );
+            this._stack.pop();
+
+        } catch (err) {
+            logger.error(`Failed to resolve ${name}@${range}: ${err.message}`);
+            throw err;
+        }
+    }
+
+    // ── Analysis helpers ────────────────────────────────────────────────────────
+
+    /**
+     * Identifies package name collisions and suggests resolution to the highest version.
+     * 
+     * @returns {Object[]} List of duplicate packages and their versions
+     */
+    deduplicate() {
+        const byName = new Map();
+        for (const [key, meta] of this._resolved) {
+            if (!byName.has(meta.name)) byName.set(meta.name, []);
+            byName.get(meta.name).push(meta);
+        }
+        const dupes = [];
+        for (const [name, metas] of byName) {
+            if (metas.length > 1) {
+                dupes.push({ name, versions: metas.map(m => m.version) });
+            }
+        }
+        return dupes;
+    }
+
+    /**
+     * Traverses the resolved dependency graph to identify circular references.
+     * 
+     * @returns {string[]} An array of strings describing the detected cycles (e.g., "A → B → A")
+     */
+    findCircular() {
+        const cycles = [];
+        const visited = new Set();
+        const path = [];
+
+        const dfs = (key) => {
+            if (path.includes(key)) {
+                const cycle = path.slice(path.indexOf(key));
+                cycles.push(cycle.join(' → ') + ' → ' + key);
+                return;
+            }
+            if (visited.has(key)) return;
+            visited.add(key);
+            path.push(key);
+
+            const meta = this._resolved.get(key);
+            if (meta) {
+                // We must match dependency ranges to their ACTUAL resolved versions in this._resolved
+                for (const [depName, depRange] of Object.entries(meta.deps)) {
+                    // Find the version of depName that was actually resolved
+                    for (const [resKey, resMeta] of this._resolved) {
+                        if (resMeta.name === depName && semver.satisfies(resMeta.version, depRange)) {
+                            dfs(resKey);
+                        }
+                    }
+                }
+            }
+            path.pop();
+        };
+
+        for (const [key] of this._resolved) dfs(key);
+        return [...new Set(cycles)];
+    }
+
+    /**
+     * Returns the complete flat map of resolved dependency metadata.
+     * @type {Map<string, Object>}
+     */
+    get resolved() { return this._resolved; }
+}
+
+module.exports = Resolver;