@pgcorp/ui-kit 0.9.0 → 0.10.0

package/src/components/shared/data-display/diff.ts

@@ -0,0 +1,541 @@
+import type { CodeEditorLanguageContract } from '../../../internal/codeEditorContract'
+import { computeDiffModel } from '../../../internal/diffEngine'
+import {
+  validateBoundedInteger,
+  validateExactString,
+  validateNonEmptyString,
+} from '../../../internal/runtimeContract'
+import { validateCodeEditorLanguage } from '../../../internal/codeEditorContract'
+
+export type SDiffSourceRevision = string | number
+export type SDiffLanguage = CodeEditorLanguageContract
+
+/** Exact text input. UI labels and revisions remain metadata and never participate in line equality. */
+export interface SDiffSource {
+  readonly text: string
+  readonly label?: string
+  readonly revision?: SDiffSourceRevision
+  readonly language?: SDiffLanguage
+}
+
+export interface SDiffComputationOptions {
+  readonly contextLines?: number
+}
+
+export type SDiffLineBreak = 'lf' | 'crlf' | 'none'
+export type SDiffLineKind = 'unchanged' | 'removed' | 'added'
+
+export interface SDiffLineSide {
+  readonly lineNumber: number
+  readonly text: string
+  readonly lineBreak: SDiffLineBreak
+}
+
+/** One semantic line operation. Missing sides are omitted instead of encoded as null. */
+export interface SDiffLine {
+  readonly id: string
+  readonly kind: SDiffLineKind
+  readonly before?: SDiffLineSide
+  readonly after?: SDiffLineSide
+}
+
+export interface SDiffHunk {
+  readonly id: string
+  readonly lineStart: number
+  readonly lineEnd: number
+  readonly beforeStart: number
+  readonly beforeLineCount: number
+  readonly afterStart: number
+  readonly afterLineCount: number
+}
+
+/** Hidden unchanged interval between hunk windows. Indices use the half-open result.lines domain. */
+export interface SDiffGap {
+  readonly id: string
+  readonly lineStart: number
+  readonly lineEnd: number
+  readonly beforeStart: number
+  readonly afterStart: number
+  readonly lineCount: number
+}
+
+export interface SDiffSourceSnapshot {
+  readonly lineCount: number
+  readonly label?: string
+  readonly revision?: SDiffSourceRevision
+  readonly language?: SDiffLanguage
+}
+
+export interface SDiffSummary {
+  readonly beforeLineCount: number
+  readonly afterLineCount: number
+  readonly unchangedLineCount: number
+  readonly removedLineCount: number
+  readonly addedLineCount: number
+  readonly changedLineCount: number
+}
+
+/** Serializable, presentation-neutral result shared by synchronous and worker execution paths. */
+export interface SDiffResult {
+  readonly before: SDiffSourceSnapshot
+  readonly after: SDiffSourceSnapshot
+  readonly lines: readonly SDiffLine[]
+  readonly hunks: readonly SDiffHunk[]
+  readonly gaps: readonly SDiffGap[]
+  readonly summary: SDiffSummary
+}
+
+export const S_DIFF_DEFAULT_CONTEXT_LINES = 3
+export const S_DIFF_MAX_CONTEXT_LINES = 100
+
+const SOURCE_KEYS = new Set(['text', 'label', 'revision', 'language'])
+const OPTIONS_KEYS = new Set(['contextLines'])
+const RESULT_KEYS = new Set(['before', 'after', 'lines', 'hunks', 'gaps', 'summary'])
+const SNAPSHOT_KEYS = new Set(['lineCount', 'label', 'revision', 'language'])
+const LINE_KEYS = new Set(['id', 'kind', 'before', 'after'])
+const LINE_SIDE_KEYS = new Set(['lineNumber', 'text', 'lineBreak'])
+const HUNK_KEYS = new Set([
+  'id',
+  'lineStart',
+  'lineEnd',
+  'beforeStart',
+  'beforeLineCount',
+  'afterStart',
+  'afterLineCount',
+])
+const GAP_KEYS = new Set(['id', 'lineStart', 'lineEnd', 'beforeStart', 'afterStart', 'lineCount'])
+const SUMMARY_KEYS = new Set([
+  'beforeLineCount',
+  'afterLineCount',
+  'unchangedLineCount',
+  'removedLineCount',
+  'addedLineCount',
+  'changedLineCount',
+])
+const LINE_KINDS = ['unchanged', 'removed', 'added'] as const
+const LINE_BREAKS = ['lf', 'crlf', 'none'] as const
+
+function assertPlainExactRecord(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  allowed: ReadonlySet<string>,
+): Record<string, unknown> {
+  if (
+    typeof value !== 'object'
+    || value === null
+    || Array.isArray(value)
+    || Object.getPrototypeOf(value) !== Object.prototype
+  ) {
+    throw new TypeError(
+      `${owner}: ${coordinate} должен быть plain object. / ${owner}: ${coordinate} must be a plain object.`,
+    )
+  }
+  const record = value as Record<string, unknown>
+  const unexpected = Object.keys(record).filter((key) => !allowed.has(key))
+  if (unexpected.length > 0) {
+    throw new TypeError(
+      `${owner}.${coordinate}: неизвестные поля ${unexpected.map((key) => JSON.stringify(key)).join(', ')}. `
+      + `/ ${owner}.${coordinate}: unknown fields ${unexpected.map((key) => JSON.stringify(key)).join(', ')}.`,
+    )
+  }
+  return record
+}
+
+function validateStableString(owner: string, coordinate: string, value: unknown): string {
+  const validated = validateNonEmptyString(owner, coordinate, value)
+  if (validated !== validated.trim()) {
+    throw new TypeError(
+      `${owner}: ${coordinate} не должен содержать окружающие пробелы. `
+      + `/ ${owner}: ${coordinate} must not contain surrounding whitespace.`,
+    )
+  }
+  return validated
+}
+
+function validateRevision(owner: string, coordinate: string, value: unknown): SDiffSourceRevision {
+  if (typeof value === 'string') return validateStableString(owner, coordinate, value)
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) return value
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть непустой строкой или неотрицательным safe integer. `
+    + `/ ${owner}: ${coordinate} must be a non-empty string or non-negative safe integer.`,
+  )
+}
+
+function validateLanguage(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): SDiffLanguage {
+  const language = validateCodeEditorLanguage(`${owner}.${coordinate}`, value)
+  return Object.freeze(language)
+}
+
+/** Validates an exact source record without coercion or newline normalization. */
+export function validateDiffSource(owner: string, coordinate: string, value: unknown): SDiffSource {
+  const record = assertPlainExactRecord(owner, coordinate, value, SOURCE_KEYS)
+  if (typeof record.text !== 'string') {
+    throw new TypeError(
+      `${owner}: ${coordinate}.text должен быть string. / ${owner}: ${coordinate}.text must be a string.`,
+    )
+  }
+  return Object.freeze({
+    text: record.text,
+    ...(record.label === undefined
+      ? {}
+      : { label: validateNonEmptyString(owner, `${coordinate}.label`, record.label) }),
+    ...(record.revision === undefined
+      ? {}
+      : { revision: validateRevision(owner, `${coordinate}.revision`, record.revision) }),
+    ...(record.language === undefined
+      ? {}
+      : { language: validateLanguage(owner, `${coordinate}.language`, record.language) }),
+  })
+}
+
+/** Validates computation options and supplies the documented context default. */
+export function validateDiffComputationOptions(
+  owner: string,
+  value: unknown,
+): Required<SDiffComputationOptions> {
+  const record = value === undefined
+    ? {}
+    : assertPlainExactRecord(owner, 'options', value, OPTIONS_KEYS)
+  return Object.freeze({
+    contextLines: validateBoundedInteger(
+      owner,
+      'options.contextLines',
+      record.contextLines ?? S_DIFF_DEFAULT_CONTEXT_LINES,
+      { minimum: 0, maximum: S_DIFF_MAX_CONTEXT_LINES },
+    ),
+  })
+}
+
+function validateSnapshot(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): SDiffSourceSnapshot {
+  const record = assertPlainExactRecord(owner, coordinate, value, SNAPSHOT_KEYS)
+  return Object.freeze({
+    lineCount: validateBoundedInteger(owner, `${coordinate}.lineCount`, record.lineCount, {
+      minimum: 0,
+      maximum: Number.MAX_SAFE_INTEGER,
+    }),
+    ...(record.label === undefined
+      ? {}
+      : { label: validateNonEmptyString(owner, `${coordinate}.label`, record.label) }),
+    ...(record.revision === undefined
+      ? {}
+      : { revision: validateRevision(owner, `${coordinate}.revision`, record.revision) }),
+    ...(record.language === undefined
+      ? {}
+      : { language: validateLanguage(owner, `${coordinate}.language`, record.language) }),
+  })
+}
+
+function validateLineSide(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  maximumLineNumber: number,
+): SDiffLineSide {
+  const record = assertPlainExactRecord(owner, coordinate, value, LINE_SIDE_KEYS)
+  if (typeof record.text !== 'string') {
+    throw new TypeError(`${owner}: ${coordinate}.text должен быть string. / ${owner}: ${coordinate}.text must be a string.`)
+  }
+  return Object.freeze({
+    lineNumber: validateBoundedInteger(owner, `${coordinate}.lineNumber`, record.lineNumber, {
+      minimum: 1,
+      maximum: maximumLineNumber,
+    }),
+    text: record.text,
+    lineBreak: validateExactString(owner, `${coordinate}.lineBreak`, record.lineBreak, LINE_BREAKS),
+  })
+}
+
+function validateLine(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  beforeLineCount: number,
+  afterLineCount: number,
+): SDiffLine {
+  const record = assertPlainExactRecord(owner, coordinate, value, LINE_KEYS)
+  const kind = validateExactString(owner, `${coordinate}.kind`, record.kind, LINE_KINDS)
+  const before = record.before === undefined
+    ? undefined
+    : validateLineSide(owner, `${coordinate}.before`, record.before, beforeLineCount)
+  const after = record.after === undefined
+    ? undefined
+    : validateLineSide(owner, `${coordinate}.after`, record.after, afterLineCount)
+  if (kind === 'unchanged' && (before === undefined || after === undefined)) {
+    throw new TypeError(`${owner}: ${coordinate} unchanged line требует обе стороны. / unchanged line requires both sides.`)
+  }
+  if (kind === 'removed' && (before === undefined || after !== undefined)) {
+    throw new TypeError(`${owner}: ${coordinate} removed line требует только before. / removed line requires before only.`)
+  }
+  if (kind === 'added' && (before !== undefined || after === undefined)) {
+    throw new TypeError(`${owner}: ${coordinate} added line требует только after. / added line requires after only.`)
+  }
+  if (
+    kind === 'unchanged'
+    && before !== undefined
+    && after !== undefined
+    && (before.text !== after.text || before.lineBreak !== after.lineBreak)
+  ) {
+    throw new TypeError(`${owner}: ${coordinate} unchanged line содержит разные стороны. / unchanged line contains different sides.`)
+  }
+  return Object.freeze({
+    id: validateStableString(owner, `${coordinate}.id`, record.id),
+    kind,
+    ...(before === undefined ? {} : { before }),
+    ...(after === undefined ? {} : { after }),
+  })
+}
+
+function validateHunk(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  lineCount: number,
+  beforeLineCount: number,
+  afterLineCount: number,
+): SDiffHunk {
+  const record = assertPlainExactRecord(owner, coordinate, value, HUNK_KEYS)
+  const lineStart = validateBoundedInteger(owner, `${coordinate}.lineStart`, record.lineStart, {
+    minimum: 0,
+    maximum: lineCount,
+  })
+  const lineEnd = validateBoundedInteger(owner, `${coordinate}.lineEnd`, record.lineEnd, {
+    minimum: lineStart + 1,
+    maximum: lineCount,
+  })
+  return Object.freeze({
+    id: validateStableString(owner, `${coordinate}.id`, record.id),
+    lineStart,
+    lineEnd,
+    beforeStart: validateBoundedInteger(owner, `${coordinate}.beforeStart`, record.beforeStart, {
+      minimum: 1,
+      maximum: beforeLineCount + 1,
+    }),
+    beforeLineCount: validateBoundedInteger(owner, `${coordinate}.beforeLineCount`, record.beforeLineCount, {
+      minimum: 0,
+      maximum: beforeLineCount,
+    }),
+    afterStart: validateBoundedInteger(owner, `${coordinate}.afterStart`, record.afterStart, {
+      minimum: 1,
+      maximum: afterLineCount + 1,
+    }),
+    afterLineCount: validateBoundedInteger(owner, `${coordinate}.afterLineCount`, record.afterLineCount, {
+      minimum: 0,
+      maximum: afterLineCount,
+    }),
+  })
+}
+
+function validateGap(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  lineCount: number,
+  beforeLineCount: number,
+  afterLineCount: number,
+): SDiffGap {
+  const record = assertPlainExactRecord(owner, coordinate, value, GAP_KEYS)
+  const lineStart = validateBoundedInteger(owner, `${coordinate}.lineStart`, record.lineStart, {
+    minimum: 0,
+    maximum: lineCount,
+  })
+  const lineEnd = validateBoundedInteger(owner, `${coordinate}.lineEnd`, record.lineEnd, {
+    minimum: lineStart + 1,
+    maximum: lineCount,
+  })
+  const intervalLength = lineEnd - lineStart
+  return Object.freeze({
+    id: validateStableString(owner, `${coordinate}.id`, record.id),
+    lineStart,
+    lineEnd,
+    beforeStart: validateBoundedInteger(owner, `${coordinate}.beforeStart`, record.beforeStart, {
+      minimum: 1,
+      maximum: beforeLineCount,
+    }),
+    afterStart: validateBoundedInteger(owner, `${coordinate}.afterStart`, record.afterStart, {
+      minimum: 1,
+      maximum: afterLineCount,
+    }),
+    lineCount: validateBoundedInteger(owner, `${coordinate}.lineCount`, record.lineCount, {
+      minimum: intervalLength,
+      maximum: intervalLength,
+    }),
+  })
+}
+
+function validateSummary(owner: string, value: unknown): SDiffSummary {
+  const record = assertPlainExactRecord(owner, 'summary', value, SUMMARY_KEYS)
+  const readCount = (coordinate: string): number => validateBoundedInteger(
+    owner,
+    `summary.${coordinate}`,
+    record[coordinate],
+    { minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+  )
+  return Object.freeze({
+    beforeLineCount: readCount('beforeLineCount'),
+    afterLineCount: readCount('afterLineCount'),
+    unchangedLineCount: readCount('unchangedLineCount'),
+    removedLineCount: readCount('removedLineCount'),
+    addedLineCount: readCount('addedLineCount'),
+    changedLineCount: readCount('changedLineCount'),
+  })
+}
+
+/** Validates a worker or persisted result and all cross-record line/count invariants. */
+export function validateDiffResult(owner: string, value: unknown): SDiffResult {
+  const record = assertPlainExactRecord(owner, 'result', value, RESULT_KEYS)
+  const before = validateSnapshot(owner, 'result.before', record.before)
+  const after = validateSnapshot(owner, 'result.after', record.after)
+  if (!Array.isArray(record.lines) || !Array.isArray(record.hunks) || !Array.isArray(record.gaps)) {
+    throw new TypeError(`${owner}: result lines/hunks/gaps должны быть arrays. / result lines/hunks/gaps must be arrays.`)
+  }
+  const lines = record.lines.map((line, index) => validateLine(
+    owner,
+    `result.lines[${index}]`,
+    line,
+    before.lineCount,
+    after.lineCount,
+  ))
+  let nextBeforeLine = 1
+  let nextAfterLine = 1
+  const beforeSides: SDiffLineSide[] = []
+  const afterSides: SDiffLineSide[] = []
+  const counts = { unchanged: 0, removed: 0, added: 0 }
+  for (const [index, line] of lines.entries()) {
+    if (line.before !== undefined && line.before.lineNumber !== nextBeforeLine) {
+      throw new RangeError(`${owner}: result.lines[${index}].before.lineNumber нарушает последовательность.`)
+    }
+    if (line.after !== undefined && line.after.lineNumber !== nextAfterLine) {
+      throw new RangeError(`${owner}: result.lines[${index}].after.lineNumber нарушает последовательность.`)
+    }
+    if (line.before !== undefined) {
+      beforeSides.push(line.before)
+      nextBeforeLine += 1
+    }
+    if (line.after !== undefined) {
+      afterSides.push(line.after)
+      nextAfterLine += 1
+    }
+    counts[line.kind] += 1
+  }
+  if (nextBeforeLine - 1 !== before.lineCount || nextAfterLine - 1 !== after.lineCount) {
+    throw new RangeError(`${owner}: result line inventory не соответствует source snapshots.`)
+  }
+  for (const [sideName, sides] of [['before', beforeSides], ['after', afterSides]] as const) {
+    const invalidTerminatorIndex = sides.findIndex(
+      (side, index) => index < sides.length - 1 && side.lineBreak === 'none',
+    )
+    if (invalidTerminatorIndex !== -1) {
+      throw new RangeError(
+        `${owner}: result ${sideName} line ${invalidTerminatorIndex + 1} теряет межстрочный terminator.`,
+      )
+    }
+  }
+  const hunks = record.hunks.map((hunk, index) => validateHunk(
+    owner,
+    `result.hunks[${index}]`,
+    hunk,
+    lines.length,
+    before.lineCount,
+    after.lineCount,
+  ))
+  const gaps = record.gaps.map((gap, index) => validateGap(
+    owner,
+    `result.gaps[${index}]`,
+    gap,
+    lines.length,
+    before.lineCount,
+    after.lineCount,
+  ))
+  for (const [index, hunk] of hunks.entries()) {
+    if (!lines.slice(hunk.lineStart, hunk.lineEnd).some((line) => line.kind !== 'unchanged')) {
+      throw new RangeError(`${owner}: result.hunks[${index}] не содержит changed line.`)
+    }
+  }
+  for (const [index, gap] of gaps.entries()) {
+    if (lines.slice(gap.lineStart, gap.lineEnd).some((line) => line.kind !== 'unchanged')) {
+      throw new RangeError(`${owner}: result.gaps[${index}] содержит changed line.`)
+    }
+  }
+  const ids = new Set<string>()
+  for (const segment of [...hunks, ...gaps]) {
+    if (ids.has(segment.id)) throw new RangeError(`${owner}: duplicate result segment id ${JSON.stringify(segment.id)}.`)
+    ids.add(segment.id)
+  }
+  if (counts.removed + counts.added === 0) {
+    if (hunks.length !== 0 || gaps.length !== 0) {
+      throw new RangeError(`${owner}: unchanged result не должен содержать hunks/gaps.`)
+    }
+  } else {
+    const segments = [
+      ...hunks.map((hunk) => ({ kind: 'hunk' as const, value: hunk })),
+      ...gaps.map((gap) => ({ kind: 'gap' as const, value: gap })),
+    ].sort((left, right) => left.value.lineStart - right.value.lineStart)
+    let expectedStart = 0
+    for (const segment of segments) {
+      if (segment.value.lineStart !== expectedStart) {
+        throw new RangeError(`${owner}: result hunks/gaps не образуют exact partition lines.`)
+      }
+      expectedStart = segment.value.lineEnd
+      const slice = lines.slice(segment.value.lineStart, segment.value.lineEnd)
+      const beforeCount = slice.filter((line) => line.before !== undefined).length
+      const afterCount = slice.filter((line) => line.after !== undefined).length
+      const expectedBeforeStart = lines
+        .slice(0, segment.value.lineStart)
+        .filter((line) => line.before !== undefined).length + 1
+      const expectedAfterStart = lines
+        .slice(0, segment.value.lineStart)
+        .filter((line) => line.after !== undefined).length + 1
+      if (
+        segment.value.beforeStart !== expectedBeforeStart
+        || segment.value.afterStart !== expectedAfterStart
+        || (segment.kind === 'hunk'
+          && (segment.value.beforeLineCount !== beforeCount || segment.value.afterLineCount !== afterCount))
+      ) {
+        throw new RangeError(`${owner}: result segment coordinates не соответствуют lines.`)
+      }
+    }
+    if (expectedStart !== lines.length) {
+      throw new RangeError(`${owner}: result hunks/gaps не покрывают lines полностью.`)
+    }
+  }
+  const summary = validateSummary(owner, record.summary)
+  if (
+    summary.beforeLineCount !== before.lineCount
+    || summary.afterLineCount !== after.lineCount
+    || summary.unchangedLineCount !== counts.unchanged
+    || summary.removedLineCount !== counts.removed
+    || summary.addedLineCount !== counts.added
+    || summary.changedLineCount !== counts.removed + counts.added
+  ) {
+    throw new RangeError(`${owner}: result.summary не соответствует lines/source snapshots.`)
+  }
+  return Object.freeze({
+    before,
+    after,
+    lines: Object.freeze(lines),
+    hunks: Object.freeze(hunks),
+    gaps: Object.freeze(gaps),
+    summary,
+  })
+}
+
+/** Computes the canonical deterministic result on the current thread. Large UI inputs use the worker runtime. */
+export function computeDiff(
+  beforeValue: unknown,
+  afterValue: unknown,
+  optionsValue?: unknown,
+): SDiffResult {
+  const before = validateDiffSource('computeDiff', 'before', beforeValue)
+  const after = validateDiffSource('computeDiff', 'after', afterValue)
+  const options = validateDiffComputationOptions('computeDiff', optionsValue)
+  return computeDiffModel(before, after, options)
+}