Type Definitions

// Package metadata structure
interface PackageMetadata {
  packageName: string;        // Package name without version (e.g., 'express')
  packageVersion: string;     // Version spec (latest, 1.0.0, ^1.0.0, etc.)
  packageString: string;       // Full spec (name@version, e.g., 'express@latest')
}

// Example PackageMetadata
const pkg: PackageMetadata = {
  packageName: 'express',
  packageVersion: 'latest',
  packageString: 'express@latest'
};

// CLI parsed arguments (full)
interface CliArgsFull {
  packages: string[];               // Normalized package specs (e.g., ['express@latest'])
  packageManager: string;           // Package manager ('npm', 'yarn', 'pnpm')
  dryRun: boolean;                  // Run checks only, don't install
  plain: boolean;                   // Plain text output (no colors/formatting)
  disableAutoContinue: boolean;     // Disable auto-continue countdown
}

// Example CliArgsFull
const args: CliArgsFull = {
  packages: ['express@latest', 'lodash@^4.17.21'],
  packageManager: 'npm',
  dryRun: false,
  plain: false,
  disableAutoContinue: false
};

// CLI parsed arguments (minimal, for npq-hero)
interface CliArgsMinimal {
  packages: string[];               // Normalized package specs
}

// Marshall orchestrator options
interface MarshallOptions {
  pkgs: string[];                   // Package specs to audit (e.g., ['express@latest'])
  progressManager?: Spinner | null; // Optional progress UI spinner
  promiseThrottleHelper?: Function; // Optional API throttling helper
  packageRepoUtils?: PackageRepoUtils; // Optional package repo utilities instance
}

// Report results output
interface ReportResults {
  countErrors: number;              // Total number of errors across all marshalls
  countWarnings: number;            // Total number of warnings across all marshalls
  resultsForPrettyPrint: string;    // Rich formatted output (with colors/box drawing)
  resultsForPlainTextPrint: string; // Plain text output (no formatting)
  summaryForPrettyPrint: string;    // Rich summary (with colors)
  summaryForPlainTextPrint: string; // Plain summary (no formatting)
  useRichFormatting: boolean;       // Whether rich format is used
}

// Example ReportResults
const report: ReportResults = {
  countErrors: 2,
  countWarnings: 5,
  resultsForPrettyPrint: '...', // Rich formatted string
  resultsForPlainTextPrint: '...', // Plain text string
  summaryForPrettyPrint: '...', // Rich summary
  summaryForPlainTextPrint: '...', // Plain summary
  useRichFormatting: true
};

// Prompt result
interface PromptResult {
  [name: string]: boolean;  // Property name specified in options (e.g., { continue: true })
}

// Example PromptResult
const promptResult: PromptResult = {
  continue: true  // User confirmed to continue
};

// Spinner interface (from ora library)
interface Spinner {
  start(text?: string): Spinner;
  stop(finalText?: string): Spinner;
  succeed(text?: string): Spinner;
  fail(text?: string): Spinner;
  warn(text?: string): Spinner;
  info(text?: string): Spinner;
  update(text: string): Spinner;
  isSpinning: boolean;
}

// Package repository utilities
interface PackageRepoUtils {
  getPackageInfo(packageName: string): Promise<any>;
  resolvePackageVersion(packageName: string, versionSpec: string, packageData?: any): Promise<string | null>;
  getPackageVersionInfo(packageName: string, version: string): Promise<any>;
}

// Example usage of PackageRepoUtils
const utils = new PackageRepoUtils();

// Get full package info
const packageInfo = await utils.getPackageInfo('express');
// Returns: {
//   name: 'express',
//   versions: { '4.18.2': {...}, ... },
//   time: { created: '...', modified: '...', '4.18.2': '...' },
//   maintainers: [...],
//   ...
// }

// Resolve version spec
const version = await utils.resolvePackageVersion('express', 'latest');
// Returns: '4.18.2'

const version2 = await utils.resolvePackageVersion('express', '^4.17.0');
// Returns: '4.18.2' (latest matching version)

// Get specific version info
const versionInfo = await utils.getPackageVersionInfo('express', '4.18.2');
// Returns: {
//   name: 'express',
//   version: '4.18.2',
//   dependencies: {...},
//   scripts: {...},
//   bin: {...},
//   ...
// }

// Exit codes returned by npq CLI
type ExitCode = 0 | 1 | -1;

// 0: Success (no errors, or user confirmed installation)
// 1: User aborted operation (Ctrl+C or explicit 'n' response)
// -1: Error occurred (package not found, validation failed, network error, etc.)