smartregistry/ts/cargo/interfaces.cargo.ts

/**
 * Cargo/crates.io registry type definitions
 * Based on: https://doc.rust-lang.org/cargo/reference/registry-index.html
 */

/**
 * Dependency specification in Cargo index
 */
export interface ICargoDepend {
  /** Dependency package name */
  name: string;
  /** Version requirement (e.g., "^0.6", ">=1.0.0") */
  req: string;
  /** Optional features to enable */
  features: string[];
  /** Whether this dependency is optional */
  optional: boolean;
  /** Whether to include default features */
  default_features: boolean;
  /** Platform-specific target (e.g., "cfg(unix)") */
  target: string | null;
  /** Dependency kind: normal, dev, or build */
  kind: 'normal' | 'dev' | 'build';
  /** Alternative registry URL */
  registry: string | null;
  /** Rename to different package name */
  package: string | null;
}

/**
 * Single version entry in the Cargo index file
 * Each line in the index file is one of these as JSON
 */
export interface ICargoIndexEntry {
  /** Crate name */
  name: string;
  /** Version string */
  vers: string;
  /** Dependencies */
  deps: ICargoDepend[];
  /** SHA256 checksum of the .crate file (hex) */
  cksum: string;
  /** Features (legacy format) */
  features: Record<string, string[]>;
  /** Features (extended format for newer Cargo) */
  features2?: Record<string, string[]>;
  /** Whether this version is yanked (deprecated but not deleted) */
  yanked: boolean;
  /** Optional native library link */
  links?: string | null;
  /** Index format version (2 is current) */
  v?: number;
  /** Minimum Rust version required */
  rust_version?: string;
}

/**
 * Metadata sent during crate publication
 */
export interface ICargoPublishMetadata {
  /** Crate name */
  name: string;
  /** Version string */
  vers: string;
  /** Dependencies */
  deps: ICargoDepend[];
  /** Features */
  features: Record<string, string[]>;
  /** Authors */
  authors: string[];
  /** Short description */
  description?: string;
  /** Documentation URL */
  documentation?: string;
  /** Homepage URL */
  homepage?: string;
  /** README content */
  readme?: string;
  /** README file path */
  readme_file?: string;
  /** Keywords for search */
  keywords?: string[];
  /** Categories */
  categories?: string[];
  /** License identifier (SPDX) */
  license?: string;
  /** License file path */
  license_file?: string;
  /** Repository URL */
  repository?: string;
  /** Badges */
  badges?: Record<string, any>;
  /** Native library link */
  links?: string | null;
  /** Minimum Rust version */
  rust_version?: string;
}

/**
 * Registry configuration (config.json)
 * Required for sparse protocol support
 */
export interface ICargoConfig {
  /** Download URL template */
  dl: string;
  /** API base URL */
  api: string;
  /** Whether authentication is required for downloads */
  'auth-required'?: boolean;
}

/**
 * Search result for a single crate
 */
export interface ICargoSearchResult {
  /** Crate name */
  name: string;
  /** Latest/maximum version */
  max_version: string;
  /** Description */
  description: string;
}

/**
 * Search response structure
 */
export interface ICargoSearchResponse {
  /** Array of matching crates */
  crates: ICargoSearchResult[];
  /** Metadata about results */
  meta: {
    /** Total number of results */
    total: number;
  };
}

/**
 * Error response structure
 */
export interface ICargoError {
  /** Array of error details */
  errors: Array<{
    /** Error message */
    detail: string;
  }>;
}

/**
 * Publish success response
 */
export interface ICargoPublishResponse {
  /** Warnings from validation */
  warnings: {
    /** Invalid categories */
    invalid_categories: string[];
    /** Invalid badges */
    invalid_badges: string[];
    /** Other warnings */
    other: string[];
  };
}

/**
 * Yank/Unyank response
 */
export interface ICargoYankResponse {
  /** Success indicator */
  ok: boolean;
}