// Data-import DOMAIN — shared primitive value types used across the mapping engine, the
// validators, the Items List parser, and the state machines. Pure (framework-free).

/**
 * A file staged for a Direct Upload, reduced to the only attributes the domain reasons about.
 * `relativePath` is the path *within the selected folder/drop* (e.g. `study1/series1/img001.dcm`)
 * — the presentation layer maps a browser `File` (its `webkitRelativePath` or bare `name`) into
 * this shape. Keeping the engine on a plain interface (not `File`) makes §5 trivially unit-testable
 * with zero `File` construction.
 */
export interface StagedFile {
  /** Bare file name including extension, e.g. `img001.dcm`. */
  name: string;
  /** Path relative to the dropped root; equals `name` when no folder structure is present. */
  relativePath: string;
  /** Size in bytes (used for progress/limits; not for mapping decisions). */
  size: number;
  /**
   * The underlying browser File, when staged from a Direct Upload picker. Optional and IGNORED by
   * the mapping engine + validators (they reason only on name/relativePath/size) — it rides along
   * so the presentation/infrastructure layers can stream the actual bytes. Domain tests omit it.
   */
  file?: File;
}

/**
 * A structured, per-item domain error. `code` is stable/machine-readable (for tests + i18n);
 * `message` is a human (Vietnamese) string. `entry`/`file` locate the offending Items List task
 * or staged file so the UI can report errors per-row (spec rule P2).
 */
export interface ImportError {
  code: ImportErrorCode;
  message: string;
  /** Items List task name this error belongs to, if any. */
  entry?: string;
  /** Staged file / item path this error belongs to, if any. */
  file?: string;
}

export type ImportErrorCode =
  | 'MIXED_TYPES' // D1
  | 'GROUP_BY_STUDY_UNSUPPORTED' // D2 / MAP3
  | 'UNSUPPORTED_FORMAT' // D3 / C5
  | 'INVALID_STRUCTURE' // D4
  | 'MHD_COMPANION_MISSING' // D6
  | 'PATH_NOT_BUCKET_RELATIVE' // C2 / IL6 / V1
  | 'ITEMS_LIST_MALFORMED' // P1
  | 'ITEMS_LIST_NOT_ARRAY' // P1
  | 'ENTRY_NAME_MISSING' // IL5
  | 'ENTRY_NAME_DUPLICATE' // IL5
  | 'ENTRY_ITEMS_SHAPE' // IL3 (NIfTI single string) / IL4 (frames ordered array)
  | 'ENTRY_EMPTY' // a task with no resolvable items
  | 'GATEWAY_ERROR'; // a network/server failure surfaced from an infrastructure adapter

/** Construct an ImportError tersely. */
export function importError(
  code: ImportErrorCode,
  message: string,
  loc?: { entry?: string; file?: string },
): ImportError {
  return { code, message, ...loc };
}
