JSON contracts

export interface Envelope<T> {
  readonly x18n: number
  readonly command: string
  readonly data: T
  readonly diagnostics: readonly WireDiagnostic[]
  readonly errors: readonly ErrorInfo[]
}

/** JSON form of an error: the `toJSON()` of a nostics diagnostic, without `stack`, `cause` and `data`. */
export interface ErrorInfo {
  /** The code, such as `X18N2002`, or the JS error name of an error without a code. */
  readonly name: string
  readonly why: string
  readonly fix?: string | undefined
  readonly docs?: string | undefined
}

export interface WireDiagnostic {
  readonly project: string
  readonly code: string
  readonly severity: Severity
  readonly message: string
  readonly key: KeyString | undefined
  readonly locale: LocaleCode | undefined
  /** Path relative to the project root. */
  readonly file: string | undefined
  readonly range: WireRange | undefined
  readonly fixes: readonly Fix[]
}

export interface WireRange {
  /** 1-based. */
  readonly line: number
  /** 1-based, UTF-16 code units. */
  readonly column: number
  readonly endLine: number
  readonly endColumn: number
  /** 0-based UTF-16 offsets. */
  readonly start: number
  readonly end: number
}

export type Severity = 'error' | 'warning' | 'info' | 'hint'

export interface Fix {
  readonly title: string
  readonly ops: readonly EditOp[]
}

export type EditOp
  = | { readonly type: 'set', readonly key: KeyString, readonly locale: LocaleCode, readonly value: MessageLeaf }
    | { readonly type: 'rename', readonly from: KeyString, readonly to: KeyString, readonly usages?: boolean }
    | { readonly type: 'rename-prefix', readonly from: KeyString, readonly to: KeyString, readonly usages?: boolean }
    | { readonly type: 'delete', readonly key: KeyString, readonly locales?: 'all' | readonly LocaleCode[] }
    | { readonly type: 'extract', readonly items: readonly ExtractItem[] }
    /** Re-write resources with the configured sort and indent. */
    | { readonly type: 'format', readonly paths?: readonly string[] }

{
  "de": {
    "app.title": "Meine App",
    "nav.home": "Start"
  }
}

export interface ExtractPlanFile {
  readonly x18n: 1
  readonly project: string
  readonly items: readonly ExtractCandidate[]
}

export interface ExtractCandidate {
  readonly path: string
  /** 1-based line, for display. */
  readonly line: number
  readonly kind: string
  readonly text: string
  /** The text in the file at `range`, used to detect stale plans. */
  readonly original: string
  readonly range: TextRange
  readonly attribute: string | undefined
  readonly key: KeyString
  /** True when an existing key with the same source value is reused. */
  readonly reused: boolean
  /** The message to store: template arguments become placeholders. */
  readonly value: string
  readonly replacement: string
  readonly imports: readonly string[]
  /** Other templates that also apply, for surfaces that let users choose. */
  readonly alternatives: readonly string[]
}