isomorphic-jj 1.0.0

package/src/utils/errors.js

@@ -0,0 +1,21 @@
+/**
+ * JJError - Custom error class for isomorphic-jj
+ * 
+ * Provides structured errors with error codes, context, and user-actionable suggestions.
+ */
+export class JJError extends Error {
+  /**
+   * @param {string} code - Error code (e.g., 'CHANGE_NOT_FOUND')
+   * @param {string} message - Human-readable error message
+   * @param {Object} [context={}] - Additional error context
+   * @param {string} [context.suggestion] - User-actionable suggestion
+   */
+  constructor(code, message, context = {}) {
+    super(message);
+    this.name = 'JJError';
+    this.code = code;
+    this.context = context;
+    this.details = context; // Alias for better ergonomics
+    this.suggestion = context.suggestion;
+  }
+}

package/src/utils/id-generation.js

@@ -0,0 +1,54 @@
+/**
+ * ID Generation utilities for isomorphic-jj
+ * 
+ * Generates stable change IDs and operation IDs using cryptographically secure random values.
+ */
+
+/**
+ * Generate a stable change ID
+ * 
+ * Uses 128-bit cryptographically random value encoded as 32-character hex string.
+ * Collision probability is negligible (2^128 space).
+ * 
+ * @returns {string} 32-character lowercase hex string
+ */
+export function generateChangeId() {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Generate an operation ID from operation content
+ *
+ * Uses SHA-256 hash of operation content for integrity verification.
+ *
+ * @param {Object} operation - Operation data
+ * @returns {Promise<string>} 64-character lowercase hex string (SHA-256)
+ */
+export async function generateOperationId(operation) {
+  const content = JSON.stringify({
+    timestamp: operation.timestamp,
+    user: operation.user,
+    description: operation.description,
+    parents: operation.parents,
+    view: operation.view,
+  });
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(content);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Generate a generic ID with optional prefix
+ *
+ * @param {string} prefix - Optional prefix (e.g., 'conflict', 'bookmark')
+ * @returns {string} ID string
+ */
+export function generateId(prefix = '') {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  const id = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return prefix ? `${prefix}-${id}` : id;
+}

package/src/utils/validation.js

@@ -0,0 +1,124 @@
+/**
+ * Validation utilities for isomorphic-jj
+ * 
+ * Provides validation functions for change IDs, paths, bookmark names, etc.
+ */
+
+import { JJError } from './errors.js';
+
+/**
+ * Validate a change ID
+ * 
+ * @param {string} changeId - Change ID to validate
+ * @throws {JJError} If change ID is invalid
+ */
+export function validateChangeId(changeId) {
+  if (typeof changeId !== 'string') {
+    throw new JJError('INVALID_CHANGE_ID', 'Change ID must be a string', {
+      changeId,
+      suggestion: 'Provide a valid 32-character hex string',
+    });
+  }
+
+  if (!/^[0-9a-f]{32}$/.test(changeId)) {
+    throw new JJError(
+      'INVALID_CHANGE_ID',
+      `Change ID must be 32 hexadecimal characters, got "${changeId}"`,
+      {
+        changeId,
+        suggestion: 'Use a valid change ID from log() output or use a revset expression',
+      }
+    );
+  }
+}
+
+/**
+ * Validate a file path
+ * 
+ * @param {string} path - File path to validate
+ * @throws {JJError} If path is invalid or contains path traversal
+ */
+export function validatePath(path) {
+  if (typeof path !== 'string') {
+    throw new JJError('INVALID_PATH', 'Path must be a string', {
+      path,
+    });
+  }
+
+  if (path.includes('..')) {
+    throw new JJError('INVALID_PATH', 'Path traversal (..) not allowed', {
+      path,
+      suggestion: 'Use relative paths without .. components',
+    });
+  }
+
+  if (path.startsWith('/')) {
+    throw new JJError('INVALID_PATH', 'Absolute paths not allowed', {
+      path,
+      suggestion: 'Use relative paths from repository root',
+    });
+  }
+
+  if (path.length > 4096) {
+    throw new JJError('INVALID_PATH', 'Path exceeds maximum length', {
+      path,
+      maxLength: 4096,
+      suggestion: 'Use shorter file paths',
+    });
+  }
+}
+
+/**
+ * Validate a bookmark name (follows Git ref name rules)
+ * 
+ * @param {string} name - Bookmark name to validate
+ * @throws {JJError} If bookmark name is invalid
+ */
+export function validateBookmarkName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new JJError('INVALID_BOOKMARK_NAME', 'Bookmark name must be a non-empty string', {
+      name,
+    });
+  }
+
+  // Git ref name validation rules
+  const invalidChars = /[\s*~^:?[\]\\]/;
+  if (invalidChars.test(name)) {
+    throw new JJError(
+      'INVALID_BOOKMARK_NAME',
+      'Bookmark name contains invalid characters (spaces, *, ~, ^, :, ?, [, ], \\)',
+      {
+        name,
+        suggestion: 'Use alphanumeric characters, hyphens, and forward slashes',
+      }
+    );
+  }
+
+  if (name.includes('..')) {
+    throw new JJError('INVALID_BOOKMARK_NAME', 'Bookmark name cannot contain ".."', {
+      name,
+    });
+  }
+
+  if (name.startsWith('.') || name.endsWith('.')) {
+    throw new JJError(
+      'INVALID_BOOKMARK_NAME',
+      'Bookmark name cannot start or end with "."',
+      {
+        name,
+      }
+    );
+  }
+
+  if (name.endsWith('.lock')) {
+    throw new JJError('INVALID_BOOKMARK_NAME', 'Bookmark name cannot end with ".lock"', {
+      name,
+    });
+  }
+
+  if (name.includes('//')) {
+    throw new JJError('INVALID_BOOKMARK_NAME', 'Bookmark name cannot contain "//"', {
+      name,
+    });
+  }
+}