pagan-artifact 0.3.2 → 0.3.3

package/utils/shouldIgnore/index.js

@@ -1,9 +1,25 @@
+/**
+ * Artifact - Modern version control.
+ * @author Benny Schmidt (https://github.com/bennyschmidt)
+ * @project https://github.com/bennyschmidt/artifact
+ * Module: Utility / shouldIgnore (v0.3.3)
+ */
+
 const fs = require('fs');
 const path = require('path');
 
 let memoizedRules = null;
 
+/**
+ * Parses .artignore and converts glob-like patterns into executable regex.
+ * @returns {RegExp[]} An array of compiled regex rules.
+ */
+
 function getRules () {
+  /**
+   * Return cached rules if they have already been processed.
+   */
+
   if (memoizedRules) {
     return memoizedRules;
   }
@@ -12,6 +28,10 @@ function getRules () {
   const ignorePath = path.join(root, '.artignore');
   const rules = [];
 
+  /**
+   * Read the ignore file and transform each line into a path-matching regex.
+   */
+
   if (fs.existsSync(ignorePath)) {
     const lines = fs.readFileSync(ignorePath, 'utf8').split(/\r?\n/);
 
@@ -22,6 +42,11 @@ function getRules () {
         continue;
       }
 
+      /**
+       * Escape special characters and translate wildcards (* and **)
+       * into valid regex syntax.
+       */
+
       let regexStr = line
         .replace(/[.+^${}()|[\]\\]/g, '\\$&')
         .replace(/\/\*\*\//g, '(/.+/|/)')
@@ -43,16 +68,32 @@ function getRules () {
   return rules;
 }
 
-function shouldIgnore (relPath) {
-  const normalizedPath = relPath.split(path.sep).join('/');
+/**
+ * Determines if a given relative path should be excluded from version control.
+ * @param {string} relativePath - The path to check.
+ * @returns {boolean} True if the path matches an ignore rule.
+ */
+
+function shouldIgnore (relativePath) {
+  /**
+   * Normalize path separators to forward slashes and protect the internal .art folder.
+   */
+
+  const normalizedPath = relativePath.split(path.sep).join('/');
 
   if (normalizedPath === '.art' || normalizedPath.startsWith('.art/')) {
     return true;
   }
 
+  /**
+   * Test the path against the compiled list of ignore patterns.
+   */
+
   const rules = getRules();
 
-  return rules.some(rule => rule.test(normalizedPath));
+  return rules.some(rule => {
+    return rule.test(normalizedPath);
+  });
 }
 
 module.exports = shouldIgnore;

package/workflow/index.js

@@ -1,6 +1,8 @@
 /**
- * art - Modern version control.
- * Module: Workflow (v0.3.2)
+ * Artifact - Modern version control.
+ * @author Benny Schmidt (https://github.com/bennyschmidt)
+ * @project https://github.com/bennyschmidt/artifact
+ * Module: Workflow (v0.3.3)
  */
 
 const fs = require('fs');
@@ -9,29 +11,43 @@ const crypto = require('crypto');
 
 const getStateByHash = require('../utils/getStateByHash');
 const shouldIgnore = require('../utils/shouldIgnore');
-
-const MAX_PART_SIZE = 32000000;
+const { MAX_PART_SIZE } = require('../utils/constants');
 
 /**
  * Helper to load all changes from a paginated stage directory.
+ * @param {string} artifactPath - Path to the .art directory.
+ * @returns {Object} All staged changes merged into one object.
  */
 
-function getStagedChanges(artPath) {
-  const stageDir = path.join(artPath, 'stage');
-  const manifestPath = path.join(stageDir, 'manifest.json');
+function getStagedChanges (artifactPath) {
+  /**
+   * Resolve the stage directory and locate the manifest for assembly.
+   */
+
+  const stageDirectory = path.join(artifactPath, 'stage');
+  const manifestPath = path.join(stageDirectory, 'manifest.json');
 
-  if (!fs.existsSync(stageDir) || !fs.existsSync(manifestPath)) {
+  if (!fs.existsSync(stageDirectory) || !fs.existsSync(manifestPath)) {
     return {};
   }
 
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const manifest = JSON.parse(
+    fs.readFileSync(manifestPath, 'utf8')
+  );
+
   let allChanges = {};
 
+  /**
+   * Aggregate changes from all registered manifest parts.
+   */
+
   for (const partName of manifest.parts) {
-    const partPath = path.join(stageDir, partName);
+    const partPath = path.join(stageDirectory, partName);
 
     if (fs.existsSync(partPath)) {
-      const partData = JSON.parse(fs.readFileSync(partPath, 'utf8'));
+      const partData = JSON.parse(
+        fs.readFileSync(partPath, 'utf8')
+      );
 
       Object.assign(allChanges, partData.changes);
     }
@@ -42,35 +58,51 @@ function getStagedChanges(artPath) {
 
 /**
  * Compares the working directory against the last commit and pending stage.
+ * @returns {Object} Status report containing staged, modified, and untracked files.
  */
 
 function status () {
+  /**
+   * Initialize workspace paths and retrieve active state and staging info.
+   */
+
   const root = process.cwd();
-  const artPath = path.join(root, '.art');
-  const artJsonPath = path.join(artPath, 'art.json');
+  const artifactPath = path.join(root, '.art');
+  const artifactJsonPath = path.join(artifactPath, 'art.json');
 
-  if (!fs.existsSync(artJsonPath)) {
+  if (!fs.existsSync(artifactJsonPath)) {
     throw new Error('No art repository found.');
   }
 
-  const artJson = JSON.parse(fs.readFileSync(artJsonPath, 'utf8'));
-  const activeBranch = artJson.active.branch;
+  const artifactJson = JSON.parse(
+    fs.readFileSync(artifactJsonPath, 'utf8')
+  );
+  const activeBranch = artifactJson.active.branch;
 
-  const stagedFiles = getStagedChanges(artPath);
-  const activeState = getStateByHash(activeBranch, artJson.active.parent) || {};
+  const stagedFiles = getStagedChanges(artifactPath);
+  const activeState = getStateByHash(activeBranch, artifactJson.active.parent) || {};
 
   const allFiles = fs.readdirSync(root, { recursive: true })
-    .filter(f => !fs.statSync(path.join(root, f)).isDirectory());
+    .filter(file => {
+      return !fs.statSync(path.join(root, file)).isDirectory();
+    });
 
   const untracked = [];
   const modified = [];
   const ignored = [];
 
+  /**
+   * Categorize each file by comparing its working directory state
+   * to history and staging.
+   */
+
   for (const file of allFiles) {
     const isStaged = !!stagedFiles[file];
     const isActive = !!activeState[file];
 
-    if (file === '.art' || file.startsWith(`.art${path.sep}`)) continue;
+    if (file === '.art' || file.startsWith(`.art${path.sep}`)) {
+      continue;
+    }
 
     const isIgnored = shouldIgnore(file);
 
@@ -83,7 +115,10 @@ function status () {
     if (!isStaged && !isActive) {
       untracked.push(file);
     } else if (!isStaged && isActive) {
-      const currentContent = fs.readFileSync(path.join(root, file), 'utf8');
+      const currentContent = fs.readFileSync(
+        path.join(root, file),
+        'utf8'
+      );
 
       if (currentContent !== activeState[file]) {
         modified.push(file);
@@ -93,7 +128,7 @@ function status () {
 
   return {
     activeBranch,
-    lastCommit: artJson.active.parent,
+    lastCommit: artifactJson.active.parent,
     staged: Object.keys(stagedFiles),
     modified,
     untracked,
@@ -103,144 +138,202 @@ function status () {
 
 /**
  * Updates or creates a JSON diff in the stage directory.
+ * @param {string} targetPath - Path to the file or directory to stage.
+ * @returns {string} Success message.
  */
 
- function add (targetPath) {
-   const root = process.cwd();
-   const artPath = path.join(root, '.art');
-   const stageDir = path.join(artPath, 'stage');
-   const artJsonPath = path.join(artPath, 'art.json');
-   const fullPath = path.resolve(root, targetPath);
+function add (targetPath) {
+  /**
+   * Validate target and load current repository configuration.
+   */
 
-   if (!fs.existsSync(fullPath)) {
-     throw new Error(`Path does not exist: ${targetPath}`);
-   }
+  const root = process.cwd();
+  const artifactPath = path.join(root, '.art');
+  const stageDirectory = path.join(artifactPath, 'stage');
+  const artifactJsonPath = path.join(artifactPath, 'art.json');
+  const fullPath = path.resolve(root, targetPath);
 
-   const artJson = JSON.parse(fs.readFileSync(artJsonPath, 'utf8'));
-   const activeState = getStateByHash(artJson.active.branch, artJson.active.parent) || {};
-   const currentStaged = getStagedChanges(artPath);
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(`Path does not exist: ${targetPath}`);
+  }
 
-   const stats = fs.statSync(fullPath);
-   const relativeTarget = path.relative(root, fullPath);
+  const artifactJson = JSON.parse(
+    fs.readFileSync(artifactJsonPath, 'utf8')
+  );
+  const activeState = getStateByHash(artifactJson.active.branch, artifactJson.active.parent) || {};
+  const currentStaged = getStagedChanges(artifactPath);
 
-   if (!stats.isDirectory() && shouldIgnore(relativeTarget) && !activeState[relativeTarget]) {
-     return `${relativeTarget} is being ignored.`;
-   }
+  const stats = fs.statSync(fullPath);
+  const relativeTarget = path.relative(root, fullPath);
 
-   let filesToProcess = [];
+  if (!stats.isDirectory() && shouldIgnore(relativeTarget) && !activeState[relativeTarget]) {
+    return `${relativeTarget} is being ignored.`;
+  }
 
-   if (stats.isDirectory()) {
-     filesToProcess = fs.readdirSync(fullPath, { recursive: true })
-       .filter(f => {
-         const absF = path.join(fullPath, f);
-         const relF = path.relative(root, absF);
+  let filesToProcess = [];
 
-         return !fs.statSync(absF).isDirectory() && !relF.startsWith('.art') && (!shouldIgnore(relF) || !!activeState[relF]);
-       })
-       .map(f => path.relative(root, path.join(fullPath, f)));
-   } else {
-     filesToProcess = [relativeTarget];
-   }
+  /**
+   * Identify all files to be added, respecting ignore rules unless already tracked.
+   */
 
-   if (filesToProcess.length === 0) return "No changes to add.";
+  if (stats.isDirectory()) {
+    const rawFiles = fs.readdirSync(fullPath, { recursive: true });
 
-   for (const relPath of filesToProcess) {
-     const currentContent = fs.readFileSync(path.join(root, relPath), 'utf8');
-     const previousContent = activeState[relPath];
+    for (const entry of rawFiles) {
+      const absoluteEntry = path.join(fullPath, entry);
+      const relativeEntry = path.relative(root, absoluteEntry);
 
-     if (previousContent === undefined) {
-       currentStaged[relPath] = { type: 'createFile', content: currentContent };
-     } else if (currentContent !== previousContent) {
-       let start = 0;
+      if (!fs.statSync(absoluteEntry).isDirectory() && !relativeEntry.startsWith('.art')) {
+        if (!shouldIgnore(relativeEntry) || !!activeState[relativeEntry]) {
+          filesToProcess.push(relativeEntry);
+        }
+      }
+    }
+  } else {
+    filesToProcess = [relativeTarget];
+  }
 
-       while (start < previousContent.length && start < currentContent.length && previousContent[start] === currentContent[start]) {
-         start++;
-       }
+  if (filesToProcess.length === 0) {
+    return 'No changes to add.';
+  }
 
-       let oldEnd = previousContent.length - 1;
-       let newEnd = currentContent.length - 1;
+  /**
+   * Calculate deltas for each file and update the staging map.
+   */
+
+  for (const relativePath of filesToProcess) {
+    const currentContent = fs.readFileSync(
+      path.join(root, relativePath),
+      'utf8'
+    );
+    const previousContent = activeState[relativePath];
+
+    if (previousContent === undefined) {
+      currentStaged[relativePath] = {
+        type: 'createFile',
+        content: currentContent
+      };
+    } else if (currentContent !== previousContent) {
+      let start = 0;
+
+      while (start < previousContent.length && start < currentContent.length && previousContent[start] === currentContent[start]) {
+        start++;
+      }
 
-       while (oldEnd >= start && newEnd >= start && previousContent[oldEnd] === currentContent[newEnd]) {
-         oldEnd--; newEnd--;
-       }
+      let oldEnd = previousContent.length - 1;
+      let newEnd = currentContent.length - 1;
 
-       const operations = [];
-       const deletionLength = oldEnd - start + 1;
+      while (oldEnd >= start && newEnd >= start && previousContent[oldEnd] === currentContent[newEnd]) {
+        oldEnd--;
+        newEnd--;
+      }
 
-       if (deletionLength > 0) {
-         operations.push({
-           type: 'delete',
-           position: start,
-           length: deletionLength,
-           content: previousContent.slice(start, oldEnd + 1)
-         });
-       }
+      const operations = [];
+      const deletionLength = oldEnd - start + 1;
 
-       const insertionContent = currentContent.slice(start, newEnd + 1);
+      if (deletionLength > 0) {
+        operations.push({
+          type: 'delete',
+          position: start,
+          length: deletionLength,
+          content: previousContent.slice(start, oldEnd + 1)
+        });
+      }
 
-       if (insertionContent.length > 0) {
-         operations.push({ type: 'insert', position: start, content: insertionContent });
-       }
+      const insertionContent = currentContent.slice(start, newEnd + 1);
 
-       if (operations.length > 0) {
-         currentStaged[relPath] = operations;
-       }
-     }
-   }
+      if (insertionContent.length > 0) {
+        operations.push({
+          type: 'insert',
+          position: start,
+          content: insertionContent
+        });
+      }
 
-   if (fs.existsSync(stageDir)) fs.rmSync(stageDir, { recursive: true, force: true });
+      if (operations.length > 0) {
+        currentStaged[relativePath] = operations;
+      }
+    }
+  }
 
-   fs.mkdirSync(stageDir, { recursive: true });
+  /**
+   * Serialize the staging map into paginated JSON files for efficient storage.
+   */
 
-   const stageParts = [];
+  if (fs.existsSync(stageDirectory)) {
+    fs.rmSync(stageDirectory, { recursive: true, force: true });
+  }
 
-   let currentPartChanges = {};
-   let currentSize = 0;
+  fs.mkdirSync(stageDirectory, { recursive: true });
 
-   const savePart = () => {
-     const partName = `part.${stageParts.length}.json`;
+  const stageParts = [];
 
-     fs.writeFileSync(path.join(stageDir, partName), JSON.stringify({ changes: currentPartChanges }, null, 2));
-     stageParts.push(partName);
-     currentPartChanges = {};
-     currentSize = 0;
-   };
+  let currentPartChanges = {};
+  let currentSize = 0;
+
+  const savePart = () => {
+    const partName = `part.${stageParts.length}.json`;
 
-   for (const [file, changes] of Object.entries(currentStaged)) {
-     const size = JSON.stringify(changes).length;
+    fs.writeFileSync(
+      path.join(stageDirectory, partName),
+      JSON.stringify({ changes: currentPartChanges }, null, 2)
+    );
 
-     if (currentSize + size > MAX_PART_SIZE && Object.keys(currentPartChanges).length > 0) {
-       savePart();
-     }
+    stageParts.push(partName);
+    currentPartChanges = {};
+    currentSize = 0;
+  };
 
-     currentPartChanges[file] = changes;
-     currentSize += size;
-   }
+  for (const [file, changes] of Object.entries(currentStaged)) {
+    const size = JSON.stringify(changes).length;
 
-   savePart();
+    if (currentSize + size > MAX_PART_SIZE && Object.keys(currentPartChanges).length > 0) {
+      savePart();
+    }
 
-   fs.writeFileSync(path.join(stageDir, 'manifest.json'), JSON.stringify({ parts: stageParts }, null, 2));
+    currentPartChanges[file] = changes;
+    currentSize += size;
+  }
 
-   return `Added ${filesToProcess.length} file(s) to stage.`;
- }
+  savePart();
+
+  fs.writeFileSync(
+    path.join(stageDirectory, 'manifest.json'),
+    JSON.stringify({ parts: stageParts }, null, 2)
+  );
+
+  return `Added ${filesToProcess.length} file(s) to stage.`;
+}
 
 /**
  * Finalizes the paginated stage into a paginated commit structure.
+ * @param {string} message - The commit message.
+ * @returns {string} Success summary.
  */
 
 function commit (message) {
-  if (!message) throw new Error('A commit message is required.');
+  /**
+   * Validate prerequisites for a commit and calculate the unique commit hash.
+   */
+
+  if (!message) {
+    throw new Error('A commit message is required.');
+  }
 
-  const MAX_PART_SIZE = 32000000;
-  const artPath = path.join(process.cwd(), '.art');
-  const stageDir = path.join(artPath, 'stage');
-  const artJsonPath = path.join(artPath, 'art.json');
+  const root = process.cwd();
+  const artifactPath = path.join(root, '.art');
+  const stageDirectory = path.join(artifactPath, 'stage');
+  const artifactJsonPath = path.join(artifactPath, 'art.json');
 
-  if (!fs.existsSync(stageDir)) throw new Error('Nothing to commit (stage is empty).');
+  if (!fs.existsSync(stageDirectory)) {
+    throw new Error('Nothing to commit (stage is empty).');
+  }
 
-  const stagedChanges = getStagedChanges(artPath);
-  const artJson = JSON.parse(fs.readFileSync(artJsonPath, 'utf8'));
-  const branch = artJson.active.branch;
+  const stagedChanges = getStagedChanges(artifactPath);
+  const artifactJson = JSON.parse(
+    fs.readFileSync(artifactJsonPath, 'utf8')
+  );
+  const branch = artifactJson.active.branch;
   const timestamp = Date.now();
 
   const commitHash = crypto
@@ -248,20 +341,29 @@ function commit (message) {
     .update(JSON.stringify(stagedChanges) + timestamp + message)
     .digest('hex');
 
-  const branchHistoryDir = path.join(artPath, 'history', 'local', branch);
+  const branchHistoryDirectory = path.join(artifactPath, 'history', 'local', branch);
   const commitParts = [];
 
   let currentPartChanges = {};
   let currentPartSize = 0;
 
+  /**
+   * Break the commit into paginated parts to handle large datasets.
+   */
+
   const saveCommitPart = () => {
-    if (Object.keys(currentPartChanges).length === 0) return;
+    if (Object.keys(currentPartChanges).length === 0) {
+      return;
+    }
 
     const partName = `${commitHash}.part.${commitParts.length}.json`;
 
-    fs.writeFileSync(path.join(branchHistoryDir, partName), JSON.stringify({ changes: currentPartChanges }, null, 2));
-    commitParts.push(partName);
+    fs.writeFileSync(
+      path.join(branchHistoryDirectory, partName),
+      JSON.stringify({ changes: currentPartChanges }, null, 2)
+    );
 
+    commitParts.push(partName);
     currentPartChanges = {};
     currentPartSize = 0;
   };
@@ -276,33 +378,55 @@ function commit (message) {
     currentPartChanges[filePath] = changeSet;
     currentPartSize += changeSize;
   }
+
   saveCommitPart();
 
+  /**
+   * Finalize the commit master file and update the branch manifest.
+   */
+
   const commitMaster = {
     hash: commitHash,
     message,
     timestamp,
-    parent: artJson.active.parent,
+    parent: artifactJson.active.parent,
     parts: commitParts
   };
 
-  fs.writeFileSync(path.join(branchHistoryDir, `${commitHash}.json`), JSON.stringify(commitMaster, null, 2));
+  fs.writeFileSync(
+    path.join(branchHistoryDirectory, `${commitHash}.json`),
+    JSON.stringify(commitMaster, null, 2)
+  );
 
-  const manifest = JSON.parse(fs.readFileSync(path.join(branchHistoryDir, 'manifest.json'), 'utf8'));
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(branchHistoryDirectory, 'manifest.json'), 'utf8')
+  );
 
   manifest.commits.push(commitHash);
-  fs.writeFileSync(path.join(branchHistoryDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
 
-  artJson.active.parent = commitHash;
-  fs.writeFileSync(artJsonPath, JSON.stringify(artJson, null, 2));
+  fs.writeFileSync(
+    path.join(branchHistoryDirectory, 'manifest.json'),
+    JSON.stringify(manifest, null, 2)
+  );
+
+  /**
+   * Update the active parent reference and clear the staging area.
+   */
+
+  artifactJson.active.parent = commitHash;
+
+  fs.writeFileSync(
+    artifactJsonPath,
+    JSON.stringify(artifactJson, null, 2)
+  );
 
-  fs.rmSync(stageDir, { recursive: true, force: true });
+  fs.rmSync(stageDirectory, { recursive: true, force: true });
 
-  return `[${branch} ${commitHash.slice(0, 7)}] ${message} (${commitParts.length} parts)`;
+  return `[${branch} ${commitHash.slice(0, 7)}] ${message}`;
 }
 
 module.exports = {
-  __libraryVersion: '0.3.2',
+  __libraryVersion: '0.3.3',
   __libraryAPIName: 'Workflow',
   status,
   add,