jpm-pkg 1.0.3 → 1.0.5

package/src/core/lockfile.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const path = require('node:path');
+const fs = require('node:fs');
 const { readJSONSafe, writeJSON } = require('../utils/fs');
 const { hashString } = require('../security/integrity');
 
@@ -8,28 +9,28 @@ 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", ... }
- *     },
- *     ...
- *   }
- * }
+ * Manages the jpm-lock.json file for deterministic installations.
+ * The lockfile stores exact versions and integrity hashes for all dependencies.
  */
-
 class Lockfile {
+    /**
+     * Creates an instance of the Lockfile.
+     * 
+     * @param {string} projectRoot - The absolute path to the project root directory
+     */
     constructor(projectRoot) {
+        /** @type {string} */
         this.filePath = path.join(projectRoot, LOCK_FILE);
+        /** @type {Object} */
         this._data = this._load();
     }
 
+    /**
+     * Loads the lockfile data from disk or returns a default structure.
+     * 
+     * @returns {Object} The lockfile data
+     * @private
+     */
     _load() {
         const data = readJSONSafe(this.filePath, null);
         if (!data) return { lockVersion: LOCK_VERSION, packages: {} };
@@ -37,7 +38,11 @@ class Lockfile {
     }
 
     /**
-     * Build/update lock file from a resolved package map
+     * Builds or updates the lockfile data from a resolved dependency map.
+     * Sorts keys for consistent output.
+     * 
+     * @param {Map<string, Object>} resolvedMap - Map of resolved package metadata
+     * @returns {this} The current instance for chaining
      */
     update(resolvedMap) {
         const packages = {};
@@ -65,7 +70,9 @@ class Lockfile {
     }
 
     /**
-     * Verifies if the lockfile has been tampered with.
+     * Verifies the cryptographic integrity of the lockfile packages.
+     * 
+     * @returns {boolean} True if the integrity hash matches the current package data
      */
     verify() {
         if (!this._data.integrity || !this._data.packages) return true;
@@ -73,7 +80,14 @@ class Lockfile {
         return actual === this._data.integrity;
     }
 
-    /** Add or update a single package entry */
+    /**
+     * Adds or updates a single package entry in the lockfile data.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @param {Object} meta - Package metadata
+     * @returns {this} The current instance for chaining
+     */
     setPackage(name, version, meta) {
         const key = `${name}@${version}`;
         this._data.packages[key] = {
@@ -87,42 +101,75 @@ class Lockfile {
         return this;
     }
 
-    /** Remove a package entry */
+    /**
+     * Removes a package entry from the lockfile data.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @returns {this} The current instance for chaining
+     */
     removePackage(name, version) {
         const key = `${name}@${version}`;
         delete this._data.packages[key];
         return this;
     }
 
-    /** Look up a specific package in the lock file */
+    /**
+     * Retrieves a specific package entry from the lockfile data.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @returns {Object|null} The package entry or null if not found
+     */
     getPackage(name, version) {
         return this._data.packages[`${name}@${version}`] || null;
     }
 
-    /** Check whether the lock file has a resolved entry for name@range */
+    /**
+     * Checks if the lockfile contains a specific package version.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @returns {boolean} True if the package version exists
+     */
     hasPackage(name, version) {
         return Boolean(this._data.packages[`${name}@${version}`]);
     }
 
-    /** Return all locked packages as array */
+    /**
+     * Returns an array of all package entries stored in the lockfile.
+     * 
+     * @returns {Object[]} Array of package entry objects
+     */
     allPackages() {
         return Object.values(this._data.packages);
     }
 
-    /** Write lock file to disk */
+    /**
+     * Writes the current lockfile data to disk.
+     * 
+     * @returns {this} The current instance for chaining
+     */
     save() {
         writeJSON(this.filePath, this._data, 2);
         return this;
     }
 
-    /** Raw data */
+    /**
+     * Returns the raw lockfile data structure.
+     * @type {Object}
+     */
     get data() { return this._data; }
 
-    /** Whether a lock file exists */
+    /**
+     * Checks if the lockfile exists on the filesystem.
+     * 
+     * @returns {boolean} True if the lockfile exists
+     */
     exists() {
-        const fs = require('node:fs');
         return fs.existsSync(this.filePath);
     }
 }
 
 module.exports = Lockfile;
+

package/src/core/package-json.js

@@ -3,33 +3,69 @@
 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'];
 
+/**
+ * Represents a Node.js package.json file.
+ * Provides methods for reading, validating, mutating, and persisting package metadata.
+ */
 class PackageJSON {
+    /**
+     * Creates an instance of the PackageJSON.
+     * 
+     * @param {string} filePath - Absolute path to the package.json file
+     */
     constructor(filePath) {
+        /** @type {string} */
         this.filePath = filePath;
+        /** @type {Object} */
         this._data = this._load();
     }
 
+    /**
+     * Creates a PackageJSON instance from a directory path.
+     * 
+     * @param {string} dir - Directory containing the package.json
+     * @returns {PackageJSON}
+     */
     static fromDir(dir) {
         const f = path.join(dir, 'package.json');
         return new PackageJSON(f);
     }
 
+    /**
+     * Finds and loads the nearest package.json starting from a directory.
+     * 
+     * @param {string} [startDir=process.cwd()] - Directory to start the search from
+     * @returns {PackageJSON}
+     * @throws {Error} If no package.json is found in the directory tree
+     */
     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);
     }
 
+    /**
+     * Loads the package.json data from disk.
+     * 
+     * @returns {Object} The package data or a default structure if not found
+     * @private
+     */
     _load() {
         const data = readJSONSafe(this.filePath, null);
         if (!data) return this._empty();
         return data;
     }
 
+    /**
+     * Returns a default package.json structure.
+     * Used when creating a new package or when the file is missing/invalid.
+     * 
+     * @returns {Object}
+     * @private
+     */
     _empty() {
         return {
             name: path.basename(path.dirname(this.filePath || process.cwd())),
@@ -47,22 +83,57 @@ class PackageJSON {
 
     // ── Accessors ────────────────────────────────────────────────────────────────
 
+    /** @type {string} */
     get name() { return this._data.name; }
+
+    /** @type {string} */
     get version() { return this._data.version; }
+
+    /** @type {Object.<string, string>} */
     get dependencies() { return this._data.dependencies || {}; }
+
+    /** @type {Object.<string, string>} */
     get devDependencies() { return this._data.devDependencies || {}; }
+
+    /** @type {Object.<string, string>} */
     get peerDependencies() { return this._data.peerDependencies || {}; }
+
+    /** @type {Object.<string, string>} */
     get optionalDeps() { return this._data.optionalDependencies || {}; }
+
+    /** @type {Object.<string, string>} */
     get scripts() { return this._data.scripts || {}; }
+
+    /** @type {string[]} */
     get workspaces() { return this._data.workspaces || []; }
+
+    /** @type {string} */
     get main() { return this._data.main || 'index.js'; }
+
+    /** @type {Object.<string, string>} */
     get bin() { return this._data.bin || {}; }
+
+    /** @type {Object.<string, string>} */
     get engines() { return this._data.engines || {}; }
+
+    /** @type {Object} */
     get data() { return this._data; }
+
+    /** @type {string} */
     get dir() { return path.dirname(this.filePath); }
 
     // ── Mutations ────────────────────────────────────────────────────────────────
 
+    /**
+     * Adds a dependency to the package.json.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @param {Object} [options={}] - Dependency options
+     * @param {boolean} [options.dev=false] - Whether to add as a devDependency
+     * @param {boolean} [options.exact=false] - Whether to use the exact version instead of a caret range
+     * @returns {this} The current instance for chaining
+     */
     addDependency(name, version, { dev = false, exact = false } = {}) {
         const range = exact ? version : `^${version}`;
         const key = dev ? 'devDependencies' : 'dependencies';
@@ -71,6 +142,12 @@ class PackageJSON {
         return this;
     }
 
+    /**
+     * Removes a dependency from all dependency sections.
+     * 
+     * @param {string} name - Package name to remove
+     * @returns {this} The current instance for chaining
+     */
     removeDependency(name) {
         for (const key of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
             if (this._data[key]) delete this._data[key][name];
@@ -78,16 +155,36 @@ class PackageJSON {
         return this;
     }
 
+    /**
+     * Sets a top-level field in the package.json.
+     * 
+     * @param {string} key - Field name
+     * @param {*} value - Field value
+     * @returns {this} The current instance for chaining
+     */
     setField(key, value) {
         this._data[key] = value;
         return this;
     }
 
+    /**
+     * Sets the package version.
+     * 
+     * @param {string} version - New version string
+     * @returns {this} The current instance for chaining
+     */
     setVersion(version) {
         this._data.version = version;
         return this;
     }
 
+    /**
+     * Adds or updates a script in the scripts section.
+     * 
+     * @param {string} name - Script name
+     * @param {string} command - Command to execute
+     * @returns {this} The current instance for chaining
+     */
     addScript(name, command) {
         if (!this._data.scripts) this._data.scripts = {};
         this._data.scripts[name] = command;
@@ -96,6 +193,11 @@ class PackageJSON {
 
     // ── Validation ────────────────────────────────────────────────────────────────
 
+    /**
+     * Validates the internal package data against basic npm requirements.
+     * 
+     * @returns {string[]} Array of validation error messages
+     */
     validate() {
         const errors = [];
         for (const field of REQUIRED_FIELDS) {
@@ -112,15 +214,30 @@ class PackageJSON {
 
     // ── Persistence ──────────────────────────────────────────────────────────────
 
+    /**
+     * Writes the current package data to disk.
+     * 
+     * @returns {this} The current instance for chaining
+     */
     save() {
         writeJSON(this.filePath, this._data, 2);
         return this;
     }
 
+    /**
+     * Checks if the package.json file exists on the filesystem.
+     * 
+     * @returns {boolean}
+     */
     exists() {
         return fs.existsSync(this.filePath);
     }
 
+    /**
+     * Returns a combined map of all dependencies (prod, dev, and optional).
+     * 
+     * @returns {Object.<string, string>}
+     */
     allDeps() {
         return {
             ...this.dependencies,
@@ -131,3 +248,4 @@ class PackageJSON {
 }
 
 module.exports = PackageJSON;
+