export type KnownFailureClassification =
  | "expected_failure"
  | "infra"
  | "product_bug"
  | "stale_test"
  | "test_bug";

export type KnownFailureState = "closed" | "open";

export interface KnownFailureIssueRef {
  repo: string;
  number: number;
  url: string;
}

export interface KnownFailureMatch {
  service?: string;
  type?: string;
  path: string;
  failureKey?: string;
  errorIncludes?: string;
}

export interface KnownFailureEntry {
  id: string;
  /** Exact issue-tracker title for the linked issue. */
  title: string;
  classification: KnownFailureClassification;
  state: KnownFailureState;
  issue: KnownFailureIssueRef;
  /** Product-local bug slice or route-family summary. */
  description: string;
  /** Underlying technical cause of the failure. */
  whyFailing: string;
  lastReviewedAt: string;
  matches: KnownFailureMatch[];
}

export interface KnownFailuresDocument {
  schemaVersion: 1;
  issueRepo?: string | null;
  entries: KnownFailureEntry[];
}

export interface KnownFailuresValidationResult {
  errors: string[];
  warnings: string[];
  stats: {
    entries: number;
    matches: number;
    failedTests: number;
    triagedFailedTests: number;
    untriagedFailedTests: number;
  };
}

export interface KnownFailureIssueValidationConfig {
  provider?: "github";
  mode?: "off" | "warn" | "error";
  cacheTtlSeconds?: number;
}

export interface KnownFailureIssueValidationFinding {
  code: string;
  severity: "warning" | "error";
  message: string;
}

export interface KnownFailureIssueValidationEntry {
  id: string;
  title: string;
  issue: KnownFailureIssueRef;
  observed: {
    matchedTests: number;
    executedTests: number;
    passedTests: number;
    failedTests: number;
    skippedTests: number;
    notRunTests: number;
    reproduced: boolean;
  };
  github: {
    exists: boolean | null;
    title: string | null;
    state: string | null;
    url: string | null;
    checkedAt: string | null;
    cached: boolean;
  };
  findings: KnownFailureIssueValidationFinding[];
  status: string;
}

export interface KnownFailureIssueValidationResult {
  schemaVersion: 2;
  provider: "github";
  mode: "off" | "warn" | "error";
  checkedAt: string;
  repo: {
    detected: string | null;
    remoteUrl: string | null;
    configured: string | null;
  };
  availability: {
    hasFreshData: boolean;
    usedCachedFallback: boolean;
  };
  findings: KnownFailureIssueValidationFinding[];
  summary: {
    entries: number;
    observedEntries: number;
    errors: number;
    warnings: number;
    byCode: Record<string, number>;
    byStatus: Record<string, number>;
  };
  entries: KnownFailureIssueValidationEntry[];
}

export declare function loadKnownFailuresConfig(
  productDir: string,
  config: { knownFailuresFile?: string | null } | null
): KnownFailuresDocument | null;
export declare function loadKnownFailuresDocument(
  filePath: string,
  relativePath?: string
): KnownFailuresDocument;
export declare function normalizeKnownFailuresDocument(
  document: unknown,
  relativePath?: string
): KnownFailuresDocument;
export declare function validateKnownFailuresDocument(
  document: KnownFailuresDocument,
  options?: {
    productDir?: string;
    statusArtifactPath?: string;
    statusArtifact?: unknown;
  }
): KnownFailuresValidationResult;
export declare function renderKnownFailuresMarkdown(document: KnownFailuresDocument): string;
export declare function findMatchingKnownFailureEntries(
  document: KnownFailuresDocument,
  fileSummary: {
    service?: string;
    type?: string;
    path: string;
    status?: string;
    error?: string | null;
    failureDetails?: Array<{ key?: string }>;
  }
): KnownFailureEntry[];
export declare function matchesKnownFailureEntry(
  entry: KnownFailureEntry,
  fileSummary: {
    service?: string;
    type?: string;
    path: string;
    error?: string | null;
    failureDetails?: Array<{ key?: string }>;
  }
): boolean;
export declare function buildKnownFailureFileIdentity(
  service: string,
  type: string,
  filePath: string
): string;

export declare function normalizeKnownFailureIssueValidationConfig(
  value: unknown
): {
  provider: "github";
  mode: "off" | "warn" | "error";
  cacheTtlSeconds: number;
} | null;
export declare function validateKnownFailureIssues(options: {
  productDir: string;
  document: KnownFailuresDocument | null;
  runArtifact?: unknown;
  statusArtifact?: unknown;
  config?: KnownFailureIssueValidationConfig | null;
  gitMetadata?: {
    repoSlug?: string | null;
    remoteUrl?: string | null;
  } | null;
}): Promise<KnownFailureIssueValidationResult | null>;
export declare function shouldFailKnownFailureIssueValidation(
  result: KnownFailureIssueValidationResult | null
): boolean;
export declare function buildKnownFailureIssueValidationSummaryLines(
  result: KnownFailureIssueValidationResult | null
): string[];
export declare function parseGitHubRepoSlug(remoteUrl: string | null | undefined): string | null;
