@startsimpli/ui 0.4.142 → 0.4.143

package/src/components/track-changes/__tests__/model.test.ts

@@ -0,0 +1,461 @@
+/**
+ * The pure layer under the track-changes editor (bd startsim-sjuai).
+ *
+ * The assertions that matter: a server offset lands on the same CHARACTER in
+ * the editor even with emoji before it; an anchor whose quote no longer
+ * matches is never painted at a guessed place; and the minimal change between
+ * two values is word-sized and exact, so an external update moves decorations
+ * instead of collapsing them.
+ */
+import {
+  anchorFor,
+  blameNotice,
+  codePointToUtf16,
+  normalizeBlame,
+  normalizeSuggestions,
+  normalizeThreads,
+  toServerOffsets,
+  utf16ToCodePoint,
+} from '../normalize'
+import { applyTextChanges, tokenize, wordChanges } from '../word-diff'
+
+describe('offset units', () => {
+  it('converts code points to UTF-16 across an emoji', () => {
+    const text = '🚀 hi there'
+    // Python: len('🚀 ') == 2; JS: '🚀 '.length == 3
+    expect(codePointToUtf16(text, 2)).toBe(3)
+    expect(text.slice(codePointToUtf16(text, 2), codePointToUtf16(text, 4))).toBe('hi')
+    expect(utf16ToCodePoint(text, 3)).toBe(2)
+  })
+
+  it('is the identity on text with no astral characters (CJK is BMP)', () => {
+    const text = '中文博客 blog'
+    for (let i = 0; i <= text.length; i++) {
+      expect(codePointToUtf16(text, i)).toBe(i)
+      expect(utf16ToCodePoint(text, i)).toBe(i)
+    }
+  })
+
+  it('clamps out-of-range offsets instead of throwing', () => {
+    expect(codePointToUtf16('ab', 9)).toBe(2)
+    expect(codePointToUtf16('ab', -1)).toBe(0)
+  })
+
+  it('round-trips an editor anchor to server offsets', () => {
+    const text = 'Launch 🚀🚀 day: big news'
+    const from = text.indexOf('big')
+    const anchor = anchorFor(text, from, from + 3)
+    expect(anchor.quote).toBe('big')
+    const server = toServerOffsets(text, anchor)
+    expect(server.from).toBe(Array.from(text.slice(0, from)).length)
+    expect(server.to - server.from).toBe(3)
+  })
+})
+
+describe('anchorFor', () => {
+  it('captures 32 characters of context on each side', () => {
+    const text = 'a'.repeat(50) + 'QUOTE' + 'b'.repeat(50)
+    const a = anchorFor(text, 50, 55)
+    expect(a).toEqual({ from: 50, to: 55, quote: 'QUOTE', prefix: 'a'.repeat(32), suffix: 'b'.repeat(32) })
+  })
+
+  it('normalizes a backwards range and clips at the edges', () => {
+    const a = anchorFor('hello world', 5, 0)
+    expect(a.from).toBe(0)
+    expect(a.quote).toBe('hello')
+    expect(a.prefix).toBe('')
+  })
+})
+
+describe('normalizeBlame', () => {
+  const text = '🚀 Ada wrote this. Machine wrote that.'
+
+  it('converts code-point spans and reads both spellings', () => {
+    const spans = normalizeBlame(
+      {
+        version: 3,
+        spans: [
+          { from: 0, to: 17, actor_label: 'ada@x.io', actor_kind: 'person', actor_kind_source: 'claim', via: 'edit', version: 2 },
+          { from: 17, to: 37, actorLabel: 'svc:n8n', actorKind: 'machine', actorKindSource: 'claim', version: 3 },
+        ],
+      },
+      text,
+    )
+    expect(spans).toHaveLength(2)
+    expect(text.slice(spans[0].from, spans[0].to)).toBe('🚀 Ada wrote this.')
+    expect(text.slice(spans[1].from, spans[1].to)).toBe(' Machine wrote that.')
+    expect(spans[1].author).toMatchObject({ label: 'svc:n8n', kind: 'machine' })
+  })
+
+  it('keeps an unknown span with its reason, and never invents an author', () => {
+    const [s] = normalizeBlame(
+      { spans: [{ from: 0, to: 5, reason: 'before history began 2026-10-06' }] },
+      'hello',
+    )
+    expect(s.author).toBeNull()
+    expect(s.unknownReason).toBe('before history began 2026-10-06')
+  })
+
+  it('treats a span with a reason as unknown even if actor columns are set', () => {
+    const [s] = normalizeBlame(
+      { spans: [{ from: 0, to: 5, actor_label: 'x', reason: 'value truncated in revision 4' }] },
+      'hello',
+    )
+    expect(s.author).toBeNull()
+    expect(s.unknownReason).toBe('value truncated in revision 4')
+  })
+
+  it('credits an accepted suggestion to its author with the acceptor beside it', () => {
+    const [s] = normalizeBlame(
+      {
+        spans: [
+          {
+            from: 0,
+            to: 5,
+            actor_label: 'author@x',
+            actor_kind: 'person',
+            via: 'accepted_suggestion',
+            accepted_by: { actor_label: 'acceptor@x', actor_kind: 'person' },
+          },
+        ],
+      },
+      'hello',
+    )
+    expect(s.via).toBe('accepted_suggestion')
+    expect(s.author?.label).toBe('author@x')
+    expect(s.acceptedBy?.label).toBe('acceptor@x')
+  })
+
+  it('drops spans outside the text rather than painting past the end', () => {
+    const spans = normalizeBlame({ spans: [{ from: 3, to: 99, actor_label: 'x' }] }, 'hello')
+    expect(spans[0]).toMatchObject({ from: 3, to: 5 })
+    expect(normalizeBlame({ spans: [{ from: 9, to: 12, actor_label: 'x' }] }, 'hello')).toHaveLength(0)
+  })
+
+  it('honours offset_unit utf16', () => {
+    const t = '🚀ab'
+    const [s] = normalizeBlame({ offset_unit: 'utf16', spans: [{ from: 2, to: 4, actor_label: 'x' }] }, t)
+    expect(t.slice(s.from, s.to)).toBe('ab')
+  })
+})
+
+describe('normalizeSuggestions', () => {
+  const text = 'Hello 👋 world, this is the draft.'
+
+  it('reads a page or a bare array, both spellings, and converts offsets', () => {
+    const cpFrom = Array.from(text.slice(0, text.indexOf('world'))).length
+    const page = {
+      results: [
+        {
+          id: 's1',
+          set_id: 'set1',
+          anchor: { from: cpFrom, to: cpFrom + 5, quote: 'world' },
+          replacement: 'planet',
+          actor_label: 'bo@x',
+          actor_kind: 'person',
+        },
+      ],
+    }
+    const [s] = normalizeSuggestions(page, text)
+    expect(text.slice(s.from, s.to)).toBe('world')
+    expect(s).toMatchObject({ id: 's1', setId: 'set1', replacement: 'planet', status: 'open', anchorState: 'mapped' })
+    expect(normalizeSuggestions([page.results[0]], text)).toHaveLength(1)
+  })
+
+  it('prefers the mapped anchor over the proposed one', () => {
+    const [s] = normalizeSuggestions(
+      [{ id: 's', anchor: { from: 0, to: 5, quote: 'Hello' }, mapped_anchor: { from: 0, to: 5, quote: 'Hello' }, replacement: 'Hi', anchor_status: 'reanchored' }],
+      text,
+    )
+    expect(s.anchorState).toBe('reanchored')
+  })
+
+  it('orphans a suggestion whose quote does not match the text at its offsets', () => {
+    const [s] = normalizeSuggestions(
+      [{ id: 's', anchor: { from: 0, to: 5, quote: 'Howdy' }, replacement: 'Hi' }],
+      text,
+    )
+    expect(s.anchorState).toBe('orphaned')
+  })
+
+  it('keeps an orphaned suggestion (never silently dropped)', () => {
+    const list = normalizeSuggestions(
+      [{ id: 's', anchor: { from: 0, to: 0, quote: 'gone' }, replacement: 'x', anchor_status: 'orphaned' }],
+      text,
+    )
+    expect(list).toHaveLength(1)
+    expect(list[0].anchorState).toBe('orphaned')
+  })
+})
+
+describe('normalizeThreads', () => {
+  it('reads anchored, field-level and tombstoned comments', () => {
+    const text = 'One two three'
+    const threads = normalizeThreads(
+      {
+        results: [
+          {
+            thread_id: 't1',
+            anchor: { from: 4, to: 7, quote: 'two' },
+            comments: [
+              { id: 'c1', body: 'why two?', actor_label: 'a@x', actor_kind: 'person' },
+              { id: 'c2', body: null, deleted: true, actor_label: 'b@x' },
+            ],
+          },
+          { id: 't2', anchor: null, resolved: true, comments: [{ id: 'c3', body: 'ok' }] },
+        ],
+      },
+      text,
+    )
+    expect(threads[0]).toMatchObject({ id: 't1', from: 4, to: 7, quote: 'two', resolved: false })
+    expect(threads[0].comments[1]).toMatchObject({ deleted: true, body: null })
+    expect(threads[1]).toMatchObject({ id: 't2', from: null, to: null, resolved: true })
+  })
+})
+
+describe('word diff', () => {
+  it('tokenizes words, whitespace, punctuation and each CJK character', () => {
+    expect(tokenize('Hi, you  there')).toEqual(['Hi', ',', ' ', 'you', '  ', 'there'])
+    expect(tokenize('中文 ok')).toEqual(['中', '文', ' ', 'ok'])
+  })
+
+  it('a one-word edit in a long single-line paragraph changes one word, not the line', () => {
+    const para = 'word '.repeat(100) + 'target ' + 'word '.repeat(100)
+    const next = para.replace('target', 'changed')
+    const changes = wordChanges(para, next)
+    expect(changes).toHaveLength(1)
+    expect(changes[0].to - changes[0].from).toBeLessThanOrEqual('target'.length)
+    expect(applyTextChanges(para, changes)).toBe(next)
+  })
+
+  it('is exact on random edits (apply(diff(a,b), a) === b)', () => {
+    let seed = 7
+    const rnd = () => ((seed = (seed * 1103515245 + 12345) & 0x7fffffff) / 0x7fffffff)
+    const words = ['alpha', 'beta', ' ', '\n', ',', '中', '🚀', 'gamma', '\r\n', '  ']
+    const gen = (n: number) => Array.from({ length: n }, () => words[Math.floor(rnd() * words.length)]).join('')
+    for (let i = 0; i < 200; i++) {
+      const a = gen(Math.floor(rnd() * 40))
+      const b = rnd() < 0.5 ? gen(Math.floor(rnd() * 40)) : a.slice(0, Math.floor(rnd() * a.length)) + gen(3) + a.slice(Math.floor(rnd() * a.length))
+      expect(applyTextChanges(a, wordChanges(a, b))).toBe(b)
+    }
+  })
+
+  it('returns no changes for identical text', () => {
+    expect(wordChanges('same', 'same')).toEqual([])
+  })
+})
+
+describe('the shapes on the RED branches (start-simpli-api feat/tc-suggestions-comments, 2026-10-07)', () => {
+  const BLOG = 'The Gulf is calm this week. Shipping rates fell sharply on Monday. Analysts expect a rebound by spring.'
+  const at = (q: string) => BLOG.indexOf(q)
+
+  it('reads a suggestion with a nested author and a position object', () => {
+    const [s] = normalizeSuggestions(
+      {
+        next: null,
+        next_cursor: null,
+        results: [
+          {
+            id: 's1',
+            set_id: 'set1',
+            field: 'blog',
+            base_version: 1,
+            status: 'open',
+            anchor: { from: at('fell sharply'), to: at('fell sharply') + 12, quote: 'fell sharply', prefix: 'rates ', suffix: ' on' },
+            position: { from: at('fell sharply'), to: at('fell sharply') + 12, state: 'mapped' },
+            replacement: 'dropped',
+            author: { sub: 'rev', label: 'rev@x.io', kind: 'person', kind_source: 'claim' },
+          },
+        ],
+      },
+      BLOG,
+    )
+    expect(s).toMatchObject({ id: 's1', setId: 'set1', quote: 'fell sharply', replacement: 'dropped', anchorState: 'mapped' })
+    expect(s.author).toEqual({ sub: 'rev', label: 'rev@x.io', kind: 'person', kindSource: 'claim' })
+    expect(BLOG.slice(s.from, s.to)).toBe('fell sharply')
+  })
+
+  it('uses the position, not the proposed anchor, after the text moved', () => {
+    const moved = 'Overall, the' + BLOG.slice(3)
+    const p = moved.indexOf('fell sharply')
+    const [s] = normalizeSuggestions(
+      [{ id: 's', anchor: { from: at('fell sharply'), to: at('fell sharply') + 12, quote: 'fell sharply' }, position: { from: p, to: p + 12, state: 'reanchored' }, replacement: 'x' }],
+      moved,
+    )
+    expect(moved.slice(s.from, s.to)).toBe('fell sharply')
+    expect(s.anchorState).toBe('reanchored')
+  })
+
+  it('reads an orphaned position (from null) as orphaned, keeping the quote', () => {
+    const [s] = normalizeSuggestions(
+      [{ id: 's', anchor: { from: 0, to: 3, quote: 'gone text' }, position: { from: null, to: null, state: 'orphaned' }, replacement: 'x' }],
+      BLOG,
+    )
+    expect(s.anchorState).toBe('orphaned')
+    expect(s.quote).toBe('gone text')
+  })
+
+  it('reads a thread with status, position and nested comment authors', () => {
+    const [t] = normalizeThreads(
+      {
+        results: [
+          {
+            id: 't1',
+            field: 'blog',
+            status: 'resolved',
+            anchor: { from: at('fell sharply'), to: at('fell sharply') + 12, quote: 'fell sharply' },
+            position: { from: at('fell sharply'), to: at('fell sharply') + 12, state: 'mapped' },
+            comments: [{ id: 'c1', body: 'Is this still true?', deleted: false, author: { sub: 'rev', label: 'rev@x.io', kind: 'person' }, edited_at: null, mentions: [] }],
+          },
+        ],
+      },
+      BLOG,
+    )
+    expect(t).toMatchObject({ id: 't1', resolved: true, quote: 'fell sharply', anchorState: 'mapped' })
+    expect(t.comments[0].author.label).toBe('rev@x.io')
+  })
+})
+
+describe('a pure insert has no quote to check, so its context is checked', () => {
+  const text = 'Rates fell sharply on Monday.'
+  const at = text.indexOf(' on Monday')
+
+  it('places an insert whose neighbouring text still matches', () => {
+    const [s] = normalizeSuggestions(
+      [{ id: 's', anchor: { from: at, to: at, quote: '', prefix: 'Rates fell sharply', suffix: ' on Monday.' }, position: { from: at, to: at, state: 'mapped' }, replacement: ' and fast' }],
+      text,
+    )
+    expect(s.anchorState).toBe('mapped')
+    expect(s.from).toBe(at)
+  })
+
+  it('orphans an insert whose position lands between different words on both sides', () => {
+    const [s] = normalizeSuggestions(
+      [{ id: 's', anchor: { from: 3, to: 3, quote: '', prefix: 'Rates fell sharply', suffix: ' on Monday.' }, position: { from: 3, to: 3, state: 'mapped' }, replacement: 'x' }],
+      text,
+    )
+    expect(s.anchorState).toBe('orphaned')
+  })
+
+  it('keeps an insert when only text further away changed (one side still matches)', () => {
+    const moved = 'Prices fell sharply on Monday.'
+    const p = moved.indexOf(' on Monday')
+    const [s] = normalizeSuggestions(
+      [{ id: 's', anchor: { from: at, to: at, quote: '', prefix: 'Rates fell sharply', suffix: ' on Monday.' }, position: { from: p, to: p, state: 'mapped' }, replacement: 'x' }],
+      moved,
+    )
+    expect(s.anchorState).toBe('mapped')
+  })
+})
+
+describe('the final blame contract (start-simpli-api #507, startsim-gulrr)', () => {
+  const text = '🚀 Old intro. Ada wrote this. Bo suggested that.'
+  const u = (s: string) => text.indexOf(s) // UTF-16, offset_unit is always utf16
+  const response = {
+    entity_id: 'e1',
+    field: 'blog',
+    version: 4,
+    history: { enabled: true, declared_by: 'type' },
+    offset_unit: 'utf16' as const,
+    length: text.length,
+    recorded: true,
+    trail_starts: { version: 2, at: '2026-10-06T06:00:00Z', from_creation: false },
+    spans: [
+      { from: 0, to: u(' Ada'), via: 'unknown', reason: 'before_history', version: null, detail: 'Written before history began on 2026-10-06.' },
+      { from: u(' Ada'), to: u(' Bo'), via: 'edit', version: 3, at: '2026-10-06T09:00:00Z', actor_sub: 'ada', actor_label: 'ada@x.io', actor_kind: 'person', actor_kind_source: 'claim' },
+      {
+        from: u(' Bo'), to: text.length, via: 'accepted_suggestion', version: 4, at: '2026-10-07T08:00:00Z',
+        actor_sub: 'bo', actor_label: 'bo@x.io', actor_kind: 'person', actor_kind_source: 'claim',
+        accepted_by: { actor_sub: 'ada', actor_label: 'ada@x.io', actor_kind: 'person', actor_kind_source: 'claim' },
+        suggestion_id: 's1', set_id: 'set1',
+      },
+    ],
+  }
+
+  it('(1) reads via "unknown" as an unknown span with no author', () => {
+    const [s] = normalizeBlame(response, text)
+    expect(s.author).toBeNull()
+    expect(s.via).toBe('unknown')
+  })
+
+  it('(2) reads the reason code, and shows the server’s sentence', () => {
+    const [s] = normalizeBlame(response, text)
+    expect(s.reason).toBe('before_history')
+    expect(s.unknownReason).toBe('Written before history began on 2026-10-06.')
+  })
+
+  it.each([
+    ['before_history', 'written before the history began'],
+    ['truncated', 'a revision was too large to store in full'],
+    ['values_omitted', 'a revision was too large to store its values'],
+    ['chain_break', 'the history has a gap here'],
+    ['unrecorded_change', 'changed without a recorded revision'],
+  ])('(2) says what %s means when the server sends no detail', (reason, words) => {
+    const [s] = normalizeBlame({ offset_unit: 'utf16', spans: [{ from: 0, to: 3, via: 'unknown', reason, version: null }] }, 'abc')
+    expect(s.unknownReason).toBe(words)
+  })
+
+  it('(3) reads accepted_by as an object with actor_* keys', () => {
+    const s = normalizeBlame(response, text)[2]
+    expect(s.via).toBe('accepted_suggestion')
+    expect(s.author).toMatchObject({ sub: 'bo', label: 'bo@x.io', kind: 'person' })
+    expect(s.acceptedBy).toEqual({ sub: 'ada', label: 'ada@x.io', kind: 'person', kindSource: 'claim' })
+  })
+
+  it('(4) reads the author from flat columns on the span', () => {
+    const s = normalizeBlame(response, text)[1]
+    expect(s.author).toEqual({ sub: 'ada', label: 'ada@x.io', kind: 'person', kindSource: 'claim' })
+    expect(text.slice(s.from, s.to)).toBe(' Ada wrote this.')
+  })
+
+  it('(5) reads spans null with recorded false as nothing to paint, and says why', () => {
+    const off = { offset_unit: 'utf16' as const, recorded: false, spans: null, detail: 'History is turned off for this type.' }
+    expect(normalizeBlame(off, text)).toEqual([])
+    expect(blameNotice(off)).toBe('Who wrote each passage is not recorded: History is turned off for this type.')
+    expect(blameNotice(response)).toBeNull()
+  })
+
+  it('(6) keeps an unknown span whose version is null', () => {
+    const [s] = normalizeBlame(response, text)
+    expect(s.version).toBeNull()
+    expect(text.slice(s.from, s.to)).toBe('🚀 Old intro.')
+  })
+
+  it('offset_unit utf16: an emoji before a span does not shift it', () => {
+    const spans = normalizeBlame(response, text)
+    expect(spans.map((s) => text.slice(s.from, s.to))).toEqual(['🚀 Old intro.', ' Ada wrote this.', ' Bo suggested that.'])
+  })
+})
+
+describe('the final suggestion and comment contract (start-simpli-api #508)', () => {
+  const BLOG = 'Rates 📉 fell sharply on Monday.'
+  const f = BLOG.indexOf('fell') // UTF-16, as the wire now is
+
+  it('reads utf16 positions without converting them as code points', () => {
+    const [s] = normalizeSuggestions(
+      {
+        offset_unit: 'utf16', version: 3, next: null, next_cursor: null,
+        results: [{
+          id: 's1', set_id: 'x', field: 'blog', status: 'open', base_version: 2,
+          anchor: { from: f, to: f + 4, quote: 'fell', prefix: 'Rates 📉 ', suffix: ' sharply' },
+          position: { state: 'mapped', from: f, to: f + 4, version: 3 },
+          replacement: 'dropped', author: { sub: 'bo', label: 'bo@x', kind: 'person', kind_source: 'claim' },
+          created_at: '2026-10-08T00:00:00Z', resolution: null,
+        }],
+      },
+      BLOG,
+    )
+    expect(BLOG.slice(s.from, s.to)).toBe('fell')
+  })
+
+  it('a null position (not open, or a record comment) is not placed and not called orphaned', () => {
+    const [s] = normalizeSuggestions(
+      [{ id: 's', status: 'accepted', anchor: { from: 0, to: 5, quote: 'Rates' }, position: null, replacement: 'R' }],
+      BLOG,
+    )
+    expect(s.status).toBe('accepted')
+    expect(s.anchorState).toBe('mapped')
+    const [t] = normalizeThreads({ offset_unit: 'utf16', version: 3, results: [{ id: 't', field: null, anchor: null, position: null, status: 'open', comments: [] }] }, BLOG)
+    expect(t).toMatchObject({ from: null, to: null, anchorState: 'mapped' })
+  })
+})