@push.rocks/smartregistry 1.5.0 → 1.6.0

package/ts/rubygems/helpers.rubygems.ts

@@ -0,0 +1,398 @@
+/**
+ * Helper functions for RubyGems registry
+ * Compact Index generation, dependency formatting, etc.
+ */
+
+import type {
+  IRubyGemsVersion,
+  IRubyGemsDependency,
+  IRubyGemsRequirement,
+  ICompactIndexVersionsEntry,
+  ICompactIndexInfoEntry,
+  IRubyGemsMetadata,
+} from './interfaces.rubygems.js';
+
+/**
+ * Generate Compact Index versions file
+ * Format: GEMNAME [-]VERSION_PLATFORM[,VERSION_PLATFORM,...] MD5
+ * @param entries - Version entries for all gems
+ * @returns Compact Index versions file content
+ */
+export function generateCompactIndexVersions(entries: ICompactIndexVersionsEntry[]): string {
+  const lines: string[] = [];
+
+  // Add metadata header
+  lines.push(`created_at: ${new Date().toISOString()}`);
+  lines.push('---');
+
+  // Add gem entries
+  for (const entry of entries) {
+    const versions = entry.versions
+      .map(v => {
+        const yanked = v.yanked ? '-' : '';
+        const platform = v.platform && v.platform !== 'ruby' ? `_${v.platform}` : '';
+        return `${yanked}${v.version}${platform}`;
+      })
+      .join(',');
+
+    lines.push(`${entry.name} ${versions} ${entry.infoChecksum}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate Compact Index info file for a gem
+ * Format: VERSION[-PLATFORM] [DEP[,DEP,...]]|REQ[,REQ,...]
+ * @param entries - Info entries for gem versions
+ * @returns Compact Index info file content
+ */
+export function generateCompactIndexInfo(entries: ICompactIndexInfoEntry[]): string {
+  const lines: string[] = ['---']; // Info files start with ---
+
+  for (const entry of entries) {
+    // Build version string with optional platform
+    const versionStr = entry.platform && entry.platform !== 'ruby'
+      ? `${entry.version}-${entry.platform}`
+      : entry.version;
+
+    // Build dependencies string
+    const depsStr = entry.dependencies.length > 0
+      ? entry.dependencies.map(formatDependency).join(',')
+      : '';
+
+    // Build requirements string (checksum is always required)
+    const reqParts: string[] = [`checksum:${entry.checksum}`];
+
+    for (const req of entry.requirements) {
+      reqParts.push(`${req.type}:${req.requirement}`);
+    }
+
+    const reqStr = reqParts.join(',');
+
+    // Combine: VERSION[-PLATFORM] [DEPS]|REQS
+    const depPart = depsStr ? ` ${depsStr}` : '';
+    lines.push(`${versionStr}${depPart}|${reqStr}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a dependency for Compact Index
+ * Format: GEM:CONSTRAINT[&CONSTRAINT]
+ * @param dep - Dependency object
+ * @returns Formatted dependency string
+ */
+export function formatDependency(dep: IRubyGemsDependency): string {
+  return `${dep.name}:${dep.requirement}`;
+}
+
+/**
+ * Parse dependency string from Compact Index
+ * @param depStr - Dependency string
+ * @returns Dependency object
+ */
+export function parseDependency(depStr: string): IRubyGemsDependency {
+  const [name, ...reqParts] = depStr.split(':');
+  const requirement = reqParts.join(':'); // Handle :: in gem names
+
+  return { name, requirement };
+}
+
+/**
+ * Generate names file (newline-separated gem names)
+ * @param names - List of gem names
+ * @returns Names file content
+ */
+export function generateNamesFile(names: string[]): string {
+  return `---\n${names.sort().join('\n')}`;
+}
+
+/**
+ * Calculate MD5 hash for Compact Index checksum
+ * @param content - Content to hash
+ * @returns MD5 hash (hex)
+ */
+export async function calculateMD5(content: string): Promise<string> {
+  const crypto = await import('crypto');
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+
+/**
+ * Calculate SHA256 hash for gem files
+ * @param data - Data to hash
+ * @returns SHA256 hash (hex)
+ */
+export async function calculateSHA256(data: Buffer): Promise<string> {
+  const crypto = await import('crypto');
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Parse gem filename to extract name, version, and platform
+ * @param filename - Gem filename (e.g., "rails-7.0.0-x86_64-linux.gem")
+ * @returns Parsed info or null
+ */
+export function parseGemFilename(filename: string): {
+  name: string;
+  version: string;
+  platform?: string;
+} | null {
+  if (!filename.endsWith('.gem')) return null;
+
+  const withoutExt = filename.slice(0, -4); // Remove .gem
+
+  // Try to match: name-version-platform
+  // Platform can contain hyphens (e.g., x86_64-linux)
+  const parts = withoutExt.split('-');
+  if (parts.length < 2) return null;
+
+  // Find version (first part that starts with a digit)
+  let versionIndex = -1;
+  for (let i = 1; i < parts.length; i++) {
+    if (/^\d/.test(parts[i])) {
+      versionIndex = i;
+      break;
+    }
+  }
+
+  if (versionIndex === -1) return null;
+
+  const name = parts.slice(0, versionIndex).join('-');
+  const version = parts[versionIndex];
+  const platform = versionIndex + 1 < parts.length
+    ? parts.slice(versionIndex + 1).join('-')
+    : undefined;
+
+  return {
+    name,
+    version,
+    platform: platform && platform !== 'ruby' ? platform : undefined,
+  };
+}
+
+/**
+ * Validate gem name
+ * Must contain only ASCII letters, numbers, _, and -
+ * @param name - Gem name
+ * @returns true if valid
+ */
+export function isValidGemName(name: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+
+/**
+ * Validate version string
+ * Basic semantic versioning check
+ * @param version - Version string
+ * @returns true if valid
+ */
+export function isValidVersion(version: string): boolean {
+  // Allow semver and other common Ruby version formats
+  return /^[\d.a-zA-Z_-]+$/.test(version);
+}
+
+/**
+ * Build version list entry for Compact Index
+ * @param versions - Version info
+ * @returns Version list string
+ */
+export function buildVersionList(versions: Array<{
+  version: string;
+  platform?: string;
+  yanked: boolean;
+}>): string {
+  return versions
+    .map(v => {
+      const yanked = v.yanked ? '-' : '';
+      const platform = v.platform && v.platform !== 'ruby' ? `_${v.platform}` : '';
+      return `${yanked}${v.version}${platform}`;
+    })
+    .join(',');
+}
+
+/**
+ * Parse version list from Compact Index
+ * @param versionStr - Version list string
+ * @returns Parsed versions
+ */
+export function parseVersionList(versionStr: string): Array<{
+  version: string;
+  platform?: string;
+  yanked: boolean;
+}> {
+  return versionStr.split(',').map(v => {
+    const yanked = v.startsWith('-');
+    const withoutYank = yanked ? v.substring(1) : v;
+
+    // Split on _ to separate version from platform
+    const [version, ...platformParts] = withoutYank.split('_');
+    const platform = platformParts.length > 0 ? platformParts.join('_') : undefined;
+
+    return {
+      version,
+      platform: platform && platform !== 'ruby' ? platform : undefined,
+      yanked,
+    };
+  });
+}
+
+/**
+ * Generate JSON response for /api/v1/versions/{gem}.json
+ * @param gemName - Gem name
+ * @param versions - Version list
+ * @returns JSON response object
+ */
+export function generateVersionsJson(
+  gemName: string,
+  versions: Array<{
+    version: string;
+    platform?: string;
+    uploadTime?: string;
+  }>
+): any {
+  return {
+    name: gemName,
+    versions: versions.map(v => ({
+      number: v.version,
+      platform: v.platform || 'ruby',
+      built_at: v.uploadTime,
+    })),
+  };
+}
+
+/**
+ * Generate JSON response for /api/v1/dependencies
+ * @param gems - Map of gem names to version dependencies
+ * @returns JSON response array
+ */
+export function generateDependenciesJson(gems: Map<string, Array<{
+  version: string;
+  platform?: string;
+  dependencies: IRubyGemsDependency[];
+}>>): any {
+  const result: any[] = [];
+
+  for (const [name, versions] of gems) {
+    for (const v of versions) {
+      result.push({
+        name,
+        number: v.version,
+        platform: v.platform || 'ruby',
+        dependencies: v.dependencies.map(d => ({
+          name: d.name,
+          requirements: d.requirement,
+        })),
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Update Compact Index versions file with new gem version
+ * Handles append-only semantics for the current month
+ * @param existingContent - Current versions file content
+ * @param gemName - Gem name
+ * @param newVersion - New version info
+ * @param infoChecksum - MD5 of info file
+ * @returns Updated versions file content
+ */
+export function updateCompactIndexVersions(
+  existingContent: string,
+  gemName: string,
+  newVersion: { version: string; platform?: string; yanked: boolean },
+  infoChecksum: string
+): string {
+  const lines = existingContent.split('\n');
+  const headerEndIndex = lines.findIndex(l => l === '---');
+
+  if (headerEndIndex === -1) {
+    throw new Error('Invalid Compact Index versions file');
+  }
+
+  const header = lines.slice(0, headerEndIndex + 1);
+  const entries = lines.slice(headerEndIndex + 1).filter(l => l.trim());
+
+  // Find existing entry for gem
+  const gemLineIndex = entries.findIndex(l => l.startsWith(`${gemName} `));
+
+  const versionStr = buildVersionList([newVersion]);
+
+  if (gemLineIndex >= 0) {
+    // Append to existing entry
+    const parts = entries[gemLineIndex].split(' ');
+    const existingVersions = parts[1];
+    const updatedVersions = `${existingVersions},${versionStr}`;
+    entries[gemLineIndex] = `${gemName} ${updatedVersions} ${infoChecksum}`;
+  } else {
+    // Add new entry
+    entries.push(`${gemName} ${versionStr} ${infoChecksum}`);
+    entries.sort(); // Keep alphabetical
+  }
+
+  return [...header, ...entries].join('\n');
+}
+
+/**
+ * Update Compact Index info file with new version
+ * @param existingContent - Current info file content
+ * @param newEntry - New version entry
+ * @returns Updated info file content
+ */
+export function updateCompactIndexInfo(
+  existingContent: string,
+  newEntry: ICompactIndexInfoEntry
+): string {
+  const lines = existingContent ? existingContent.split('\n').filter(l => l !== '---') : [];
+
+  // Build version string
+  const versionStr = newEntry.platform && newEntry.platform !== 'ruby'
+    ? `${newEntry.version}-${newEntry.platform}`
+    : newEntry.version;
+
+  // Build dependencies string
+  const depsStr = newEntry.dependencies.length > 0
+    ? newEntry.dependencies.map(formatDependency).join(',')
+    : '';
+
+  // Build requirements string
+  const reqParts: string[] = [`checksum:${newEntry.checksum}`];
+  for (const req of newEntry.requirements) {
+    reqParts.push(`${req.type}:${req.requirement}`);
+  }
+  const reqStr = reqParts.join(',');
+
+  // Combine
+  const depPart = depsStr ? ` ${depsStr}` : '';
+  const newLine = `${versionStr}${depPart}|${reqStr}`;
+
+  lines.push(newLine);
+
+  return `---\n${lines.join('\n')}`;
+}
+
+/**
+ * Extract gem specification from .gem file
+ * Note: This is a simplified version. Full implementation would use tar + gzip + Marshal
+ * @param gemData - Gem file data
+ * @returns Extracted spec or null
+ */
+export async function extractGemSpec(gemData: Buffer): Promise<any | null> {
+  try {
+    // .gem files are gzipped tar archives
+    // They contain metadata.gz which has Marshal-encoded spec
+    // This is a placeholder - full implementation would need:
+    // 1. Unzip outer gzip
+    // 2. Untar to find metadata.gz
+    // 3. Unzip metadata.gz
+    // 4. Parse Ruby Marshal format
+
+    // For now, return null and expect metadata to be provided
+    return null;
+  } catch (error) {
+    return null;
+  }
+}

package/ts/rubygems/index.ts

@@ -0,0 +1,8 @@
+/**
+ * RubyGems Registry Module
+ * RubyGems/Bundler Compact Index implementation
+ */
+
+export * from './interfaces.rubygems.js';
+export * from './classes.rubygemsregistry.js';
+export * as rubygemsHelpers from './helpers.rubygems.js';

package/ts/rubygems/interfaces.rubygems.ts

@@ -0,0 +1,251 @@
+/**
+ * RubyGems Registry Type Definitions
+ * Compliant with Compact Index API and RubyGems protocol
+ */
+
+/**
+ * Gem version entry in compact index
+ */
+export interface IRubyGemsVersion {
+  /** Version number */
+  version: string;
+  /** Platform (e.g., ruby, x86_64-linux) */
+  platform?: string;
+  /** Dependencies */
+  dependencies?: IRubyGemsDependency[];
+  /** Requirements */
+  requirements?: IRubyGemsRequirement[];
+  /** Whether this version is yanked */
+  yanked?: boolean;
+  /** SHA256 checksum of .gem file */
+  checksum?: string;
+}
+
+/**
+ * Gem dependency specification
+ */
+export interface IRubyGemsDependency {
+  /** Gem name */
+  name: string;
+  /** Version requirement (e.g., ">= 1.0", "~> 2.0") */
+  requirement: string;
+}
+
+/**
+ * Gem requirements (ruby version, rubygems version, etc.)
+ */
+export interface IRubyGemsRequirement {
+  /** Requirement type (ruby, rubygems) */
+  type: 'ruby' | 'rubygems';
+  /** Version requirement */
+  requirement: string;
+}
+
+/**
+ * Complete gem metadata
+ */
+export interface IRubyGemsMetadata {
+  /** Gem name */
+  name: string;
+  /** All versions */
+  versions: Record<string, IRubyGemsVersionMetadata>;
+  /** Last modified timestamp */
+  'last-modified'?: string;
+}
+
+/**
+ * Version-specific metadata
+ */
+export interface IRubyGemsVersionMetadata {
+  /** Version number */
+  version: string;
+  /** Platform */
+  platform?: string;
+  /** Authors */
+  authors?: string[];
+  /** Description */
+  description?: string;
+  /** Summary */
+  summary?: string;
+  /** Homepage */
+  homepage?: string;
+  /** License */
+  license?: string;
+  /** Dependencies */
+  dependencies?: IRubyGemsDependency[];
+  /** Requirements */
+  requirements?: IRubyGemsRequirement[];
+  /** SHA256 checksum */
+  checksum: string;
+  /** File size */
+  size: number;
+  /** Upload timestamp */
+  'upload-time': string;
+  /** Uploader */
+  'uploaded-by': string;
+  /** Yanked status */
+  yanked?: boolean;
+  /** Yank reason */
+  'yank-reason'?: string;
+}
+
+/**
+ * Compact index versions file entry
+ * Format: GEMNAME [-]VERSION_PLATFORM[,VERSION_PLATFORM,...] MD5
+ */
+export interface ICompactIndexVersionsEntry {
+  /** Gem name */
+  name: string;
+  /** Versions (with optional platform and yank flag) */
+  versions: Array<{
+    version: string;
+    platform?: string;
+    yanked: boolean;
+  }>;
+  /** MD5 checksum of info file */
+  infoChecksum: string;
+}
+
+/**
+ * Compact index info file entry
+ * Format: VERSION[-PLATFORM] [DEP[,DEP,...]]|REQ[,REQ,...]
+ */
+export interface ICompactIndexInfoEntry {
+  /** Version number */
+  version: string;
+  /** Platform (optional) */
+  platform?: string;
+  /** Dependencies */
+  dependencies: IRubyGemsDependency[];
+  /** Requirements */
+  requirements: IRubyGemsRequirement[];
+  /** SHA256 checksum */
+  checksum: string;
+}
+
+/**
+ * Gem upload request
+ */
+export interface IRubyGemsUploadRequest {
+  /** Gem file data */
+  gemData: Buffer;
+  /** Gem filename */
+  filename: string;
+}
+
+/**
+ * Gem upload response
+ */
+export interface IRubyGemsUploadResponse {
+  /** Success message */
+  message?: string;
+  /** Gem name */
+  name?: string;
+  /** Version */
+  version?: string;
+}
+
+/**
+ * Yank request
+ */
+export interface IRubyGemsYankRequest {
+  /** Gem name */
+  gem_name: string;
+  /** Version to yank */
+  version: string;
+  /** Platform (optional) */
+  platform?: string;
+}
+
+/**
+ * Yank response
+ */
+export interface IRubyGemsYankResponse {
+  /** Success indicator */
+  success: boolean;
+  /** Message */
+  message?: string;
+}
+
+/**
+ * Version info response (JSON)
+ */
+export interface IRubyGemsVersionInfo {
+  /** Gem name */
+  name: string;
+  /** Versions list */
+  versions: Array<{
+    /** Version number */
+    number: string;
+    /** Platform */
+    platform?: string;
+    /** Build date */
+    built_at?: string;
+    /** Download count */
+    downloads_count?: number;
+  }>;
+}
+
+/**
+ * Dependencies query response
+ */
+export interface IRubyGemsDependenciesResponse {
+  /** Dependencies for requested gems */
+  dependencies: Array<{
+    /** Gem name */
+    name: string;
+    /** Version */
+    number: string;
+    /** Platform */
+    platform?: string;
+    /** Dependencies */
+    dependencies: Array<{
+      name: string;
+      requirements: string;
+    }>;
+  }>;
+}
+
+/**
+ * Error response structure
+ */
+export interface IRubyGemsError {
+  /** Error message */
+  message: string;
+  /** HTTP status code */
+  status?: number;
+}
+
+/**
+ * Gem specification (extracted from .gem file)
+ */
+export interface IRubyGemsSpec {
+  /** Gem name */
+  name: string;
+  /** Version */
+  version: string;
+  /** Platform */
+  platform?: string;
+  /** Authors */
+  authors?: string[];
+  /** Email */
+  email?: string;
+  /** Homepage */
+  homepage?: string;
+  /** Summary */
+  summary?: string;
+  /** Description */
+  description?: string;
+  /** License */
+  license?: string;
+  /** Dependencies */
+  dependencies?: IRubyGemsDependency[];
+  /** Required Ruby version */
+  required_ruby_version?: string;
+  /** Required RubyGems version */
+  required_rubygems_version?: string;
+  /** Files */
+  files?: string[];
+  /** Requirements */
+  requirements?: string[];
+}