@freighttech/ui 0.13.18

package/src/backend/dynamic-table/__tests__/formula.check.test.ts

@@ -0,0 +1,257 @@
+import {
+  checkAst,
+  checkFormulaColumn,
+  columnTypeToFormulaType,
+  detectFormulaCycles,
+  fieldMetaFromColumns,
+} from '../formula/check'
+import { parseFormula } from '../formula/parse'
+import type { FormulaColumnRef, FormulaFieldMeta } from '../formula/types'
+
+// Everything asserted here happens when the user SAVES the formula. The
+// contract this file defends is that a saved view can never contain a formula
+// with an unknown reference or a cycle, so no cell ever has to discover one.
+
+const fields: FormulaFieldMeta[] = [
+  { key: 'revenue', label: 'Revenue', type: 'number' },
+  { key: 'cost', label: 'Cost', type: 'number' },
+  { key: 'ref_no', label: 'Reference', type: 'text' },
+  { key: 'etd', label: 'ETD', type: 'date' },
+  { key: 'is_paid', label: 'Paid', type: 'boolean' },
+  { key: 'mystery', label: 'Mystery', type: 'unknown' },
+]
+
+function check(expression: string) {
+  const parsed = parseFormula(expression)
+  if (!parsed.ok) throw new Error(`unparsable test input: ${expression}`)
+  return checkAst(parsed.ast, { fields })
+}
+
+function codes(expression: string): string[] {
+  const result = check(expression)
+  return result.ok ? [] : result.issues.map((i) => i.code)
+}
+
+describe('checkAst — types', () => {
+  it('types same-row arithmetic as a number', () => {
+    expect(check('revenue - cost')).toEqual({ ok: true, type: 'number' })
+  })
+
+  it('types a comparison as a boolean and a concat as text', () => {
+    expect(check('revenue > cost')).toEqual({ ok: true, type: 'boolean' })
+    expect(check("ref_no & '-' & revenue")).toEqual({ ok: true, type: 'text' })
+  })
+
+  it('takes a function result type from the library', () => {
+    expect(check('DAYS_BETWEEN(etd, TODAY())')).toEqual({ ok: true, type: 'number' })
+    expect(check('UPPER(ref_no)')).toEqual({ ok: true, type: 'text' })
+  })
+
+  it('resolves IF to the type both branches agree on, and unknown otherwise', () => {
+    expect(check('IF(is_paid, revenue, cost)')).toEqual({ ok: true, type: 'number' })
+    expect(check('IF(is_paid, revenue, ref_no)')).toEqual({ ok: true, type: 'unknown' })
+  })
+})
+
+describe('checkAst — reference errors', () => {
+  it('rejects an unknown column and names it', () => {
+    const result = check('revenue - profit')
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.issues[0].code).toBe('unknown_field')
+    expect(result.issues[0].params?.name).toBe('profit')
+  })
+
+  it('collects every problem, not just the first', () => {
+    expect(codes('missing_a + missing_b')).toEqual(['unknown_field', 'unknown_field'])
+  })
+})
+
+describe('checkAst — type errors', () => {
+  it('rejects text in arithmetic and names the column by its label', () => {
+    const result = check('revenue - ref_no')
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.issues[0].code).toBe('type_mismatch')
+    expect(result.issues[0].params?.name).toBe('Reference')
+    expect(result.issues[0].message).toBe('Reference is not a number')
+  })
+
+  it('rejects a non-boolean operand of AND', () => {
+    expect(codes('revenue AND is_paid')).toEqual(['type_mismatch'])
+  })
+
+  it('rejects an argument whose type the function does not take', () => {
+    expect(codes('UPPER(revenue)')).toEqual(['type_mismatch'])
+  })
+
+  it('rejects ordering a date against a number', () => {
+    expect(codes('etd > revenue')).toEqual(['type_mismatch'])
+  })
+
+  it('never complains about a column whose type the host did not declare', () => {
+    expect(check('mystery * 2')).toEqual({ ok: true, type: 'number' })
+    expect(check('UPPER(mystery)')).toEqual({ ok: true, type: 'text' })
+  })
+})
+
+describe('checkAst — functions', () => {
+  it('rejects an unknown function', () => {
+    const result = check('VLOOKUP(revenue)')
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.issues[0].code).toBe('unknown_function')
+    expect(result.issues[0].params?.name).toBe('VLOOKUP')
+  })
+
+  it('rejects the wrong number of arguments', () => {
+    expect(codes('IF(is_paid, revenue)')).toEqual(['arity'])
+    expect(codes('ABS(revenue, cost)')).toEqual(['arity'])
+  })
+
+  it('accepts any number of arguments for a variadic function', () => {
+    expect(check('SUM(revenue, cost, 10)')).toEqual({ ok: true, type: 'number' })
+  })
+})
+
+describe('checkAst — divide by zero', () => {
+  it('is caught at definition time when the divisor is a literal zero', () => {
+    expect(codes('revenue / 0')).toEqual(['divide_by_zero'])
+  })
+
+  it('is left to evaluation when the divisor is a column', () => {
+    expect(check('revenue / cost')).toEqual({ ok: true, type: 'number' })
+  })
+})
+
+describe('detectFormulaCycles', () => {
+  const ref = (key: string, expression: string): FormulaColumnRef => ({
+    key,
+    label: key,
+    expression,
+    resultType: 'number',
+  })
+
+  it('finds a self-reference', () => {
+    const cycles = detectFormulaCycles([ref('formula__a', 'formula__a + 1')])
+    expect(cycles.get('formula__a')).toEqual(['formula__a', 'formula__a'])
+  })
+
+  it('finds a mutual reference and flags every participant', () => {
+    const cycles = detectFormulaCycles([
+      ref('formula__a', 'formula__b + 1'),
+      ref('formula__b', 'formula__a + 1'),
+    ])
+    expect(cycles.has('formula__a')).toBe(true)
+    expect(cycles.has('formula__b')).toBe(true)
+  })
+
+  it('allows a chain that is not a cycle', () => {
+    const cycles = detectFormulaCycles([
+      ref('formula__a', 'revenue - cost'),
+      ref('formula__b', 'formula__a * 2'),
+      ref('formula__c', 'formula__b + formula__a'),
+    ])
+    expect(cycles.size).toBe(0)
+  })
+
+  it('ignores a formula that does not parse rather than crashing', () => {
+    expect(detectFormulaCycles([ref('formula__a', '((((')]).size).toBe(0)
+  })
+})
+
+describe('checkFormulaColumn', () => {
+  const margin: FormulaColumnRef = {
+    key: 'formula__margin',
+    label: 'Margin',
+    expression: 'revenue - cost',
+    resultType: 'number',
+  }
+
+  it('accepts a well-formed definition', () => {
+    const result = checkFormulaColumn({ ref: margin, fields })
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.type).toBe('number')
+  })
+
+  it('refuses a self-referencing formula at definition time', () => {
+    const result = checkFormulaColumn({
+      ref: { ...margin, expression: 'formula__margin + 1' },
+      fields,
+    })
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.issues[0].code).toBe('cycle')
+    expect(result.issues[0].message).toBe('This formula refers to itself')
+  })
+
+  it('refuses a formula that closes a cycle with an existing one', () => {
+    const other: FormulaColumnRef = {
+      key: 'formula__other',
+      label: 'Other',
+      expression: 'formula__margin * 2',
+      resultType: 'number',
+    }
+    const result = checkFormulaColumn({
+      ref: { ...margin, expression: 'formula__other - cost' },
+      fields,
+      existing: [other],
+    })
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.issues[0].code).toBe('cycle')
+  })
+
+  it('lets a formula read another formula column', () => {
+    const result = checkFormulaColumn({
+      ref: {
+        key: 'formula__margin_pct',
+        label: 'Margin %',
+        expression: 'formula__margin / revenue * 100',
+        resultType: 'number',
+      },
+      fields,
+      existing: [margin],
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('does not mistake re-saving a formula for a cycle with its own old version', () => {
+    const result = checkFormulaColumn({
+      ref: { ...margin, expression: 'revenue - cost - 1' },
+      fields,
+      existing: [margin],
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('reports a syntax error before anything else', () => {
+    const result = checkFormulaColumn({ ref: { ...margin, expression: 'revenue -' }, fields })
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.issues[0].code).toBe('syntax')
+  })
+})
+
+describe('column metadata', () => {
+  it('translates ColumnDef.type into the checker vocabulary', () => {
+    expect(columnTypeToFormulaType('numeric')).toBe('number')
+    expect(columnTypeToFormulaType('date')).toBe('date')
+    expect(columnTypeToFormulaType('boolean')).toBe('boolean')
+    expect(columnTypeToFormulaType('dropdown')).toBe('text')
+    expect(columnTypeToFormulaType(undefined)).toBe('unknown')
+  })
+
+  it('derives field metadata from column defs', () => {
+    expect(
+      fieldMetaFromColumns([
+        { data: 'revenue', title: 'Revenue', type: 'numeric' },
+        { data: 'note' },
+      ]),
+    ).toEqual([
+      { key: 'revenue', label: 'Revenue', type: 'number' },
+      { key: 'note', label: undefined, type: 'unknown' },
+    ])
+  })
+})

package/src/backend/dynamic-table/__tests__/formula.evaluate.test.ts

@@ -0,0 +1,274 @@
+import {
+  coerceToResultType,
+  compileFormulaColumns,
+  createFormulaRowEvaluator,
+  evaluateAst,
+  evaluateExpression,
+  evaluateFormulaRow,
+} from '../formula/evaluate'
+import { parseFormula } from '../formula/parse'
+import type { FormulaCellResult, FormulaColumnRef, FormulaFieldMeta } from '../formula/types'
+
+// The rule these tests defend: a formula never invents a number. A null input
+// yields EMPTY (never 0, never NaN), a bad input yields an error IN ITS OWN
+// CELL, and neither blanks the column nor throws.
+
+const fields: FormulaFieldMeta[] = [
+  { key: 'revenue', label: 'Revenue', type: 'number' },
+  { key: 'cost', label: 'Cost', type: 'number' },
+  { key: 'qty', label: 'Qty', type: 'number' },
+  { key: 'ref_no', label: 'Reference', type: 'text' },
+  { key: 'etd', label: 'ETD', type: 'date' },
+  { key: 'ata', label: 'ATA', type: 'date' },
+  { key: 'is_paid', label: 'Paid', type: 'boolean' },
+]
+
+const fieldMap = new Map(fields.map((f) => [f.key, f]))
+
+function run(expression: string, row: Record<string, unknown> = {}) {
+  const parsed = parseFormula(expression)
+  if (!parsed.ok) throw new Error(`unparsable test input: ${expression}`)
+  return evaluateAst(parsed.ast, row, { fields: fieldMap, now: () => new Date(2026, 7, 3) })
+}
+
+function value(expression: string, row: Record<string, unknown> = {}) {
+  const result = run(expression, row)
+  if (!result.ok) throw new Error(`expected a value, got ${result.issue.code}`)
+  return result.value
+}
+
+function errorCode(expression: string, row: Record<string, unknown> = {}) {
+  const result = run(expression, row)
+  if (result.ok) throw new Error(`expected an error, got ${String(result.value)}`)
+  return result.issue.code
+}
+
+describe('evaluateAst — arithmetic', () => {
+  it('computes same-row arithmetic', () => {
+    expect(value('revenue - cost', { revenue: 1000, cost: 620 })).toBe(380)
+    expect(value('revenue / qty', { revenue: 1000, qty: 4 })).toBe(250)
+  })
+
+  it('honours precedence at runtime, not only in the tree', () => {
+    expect(value('1 + 2 * 3')).toBe(7)
+    expect(value('(1 + 2) * 3')).toBe(9)
+    expect(value('10 - 3 - 2')).toBe(5)
+  })
+
+  it('reads a money string as a number, because the API returns money as text', () => {
+    expect(value('revenue - cost', { revenue: '1000.50', cost: '0.50' })).toBe(1000)
+  })
+
+  it('yields EMPTY when an operand is null — never 0 and never NaN', () => {
+    expect(value('revenue - cost', { revenue: null, cost: 620 })).toBeNull()
+    expect(value('revenue - cost', { revenue: 1000 })).toBeNull()
+    expect(value('revenue * qty', { revenue: 1000, qty: '' })).toBeNull()
+  })
+
+  it('errors on division by zero rather than yielding Infinity', () => {
+    expect(errorCode('revenue / qty', { revenue: 1000, qty: 0 })).toBe('divide_by_zero')
+  })
+
+  it('errors on text where a number is required', () => {
+    expect(errorCode('revenue - ref_no', { revenue: 10, ref_no: 'MSCU1' })).toBe('type_mismatch')
+  })
+
+  it('negates', () => {
+    expect(value('-revenue', { revenue: 5 })).toBe(-5)
+    expect(value('-revenue', { revenue: null })).toBeNull()
+  })
+})
+
+describe('evaluateAst — comparison and logic', () => {
+  it('compares numbers, text and dates', () => {
+    expect(value('revenue > cost', { revenue: 10, cost: 5 })).toBe(true)
+    expect(value("ref_no < 'B'", { ref_no: 'A' })).toBe(true)
+    expect(value('etd < ata', { etd: '2026-01-01', ata: '2026-02-01' })).toBe(true)
+  })
+
+  it('treats blank as equal to blank, as Excel does', () => {
+    expect(value('revenue = cost', { revenue: null, cost: null })).toBe(true)
+    expect(value('revenue = cost', { revenue: null, cost: 0 })).toBe(false)
+  })
+
+  it('compares a numeric string with a number by value', () => {
+    expect(value('revenue = 10', { revenue: '10' })).toBe(true)
+  })
+
+  it('yields EMPTY when ordering against a blank', () => {
+    expect(value('revenue > cost', { revenue: null, cost: 5 })).toBeNull()
+  })
+
+  it('short-circuits && and ||', () => {
+    // The right operand would be a type error if it were reached.
+    expect(value('is_paid && revenue > 0', { is_paid: false, revenue: 5 })).toBe(false)
+    expect(value("is_paid || ref_no = 'x'", { is_paid: true, ref_no: 'x' })).toBe(true)
+  })
+})
+
+describe('evaluateAst — concatenation', () => {
+  it('joins values as text', () => {
+    expect(value("ref_no & '-' & revenue", { ref_no: 'MSCU1', revenue: 12 })).toBe('MSCU1-12')
+  })
+
+  it('treats a blank as the empty string so an optional suffix cannot blank the column', () => {
+    expect(value("ref_no & '-' & cost", { ref_no: 'A', cost: null })).toBe('A-')
+  })
+
+  it('is EMPTY only when both sides are blank', () => {
+    expect(value('ref_no & cost', { ref_no: null, cost: null })).toBeNull()
+  })
+})
+
+describe('coerceToResultType', () => {
+  it('coerces the final value to the column’s declared type', () => {
+    expect(coerceToResultType({ ok: true, value: '12.5' }, 'number', 'Margin')).toEqual({
+      state: 'ok',
+      value: 12.5,
+    })
+    expect(coerceToResultType({ ok: true, value: 3 }, 'text', 'Margin')).toEqual({
+      state: 'ok',
+      value: '3',
+    })
+  })
+
+  it('maps null to EMPTY and a failure to an error state', () => {
+    expect(coerceToResultType({ ok: true, value: null }, 'number', 'X')).toEqual({
+      state: 'empty',
+      value: null,
+    })
+    const errored = coerceToResultType(
+      { ok: false, issue: { code: 'divide_by_zero', message: 'Cannot divide by zero' } },
+      'number',
+      'X',
+    )
+    expect(errored.state).toBe('error')
+  })
+
+  it('errors when the value cannot be the declared type', () => {
+    const result = coerceToResultType({ ok: true, value: 'abc' }, 'number', 'Margin')
+    expect(result.state).toBe('error')
+    if (result.state !== 'error') return
+    expect(result.issue.code).toBe('type_mismatch')
+  })
+})
+
+describe('compileFormulaColumns + evaluateFormulaRow', () => {
+  const ref = (
+    key: string,
+    expression: string,
+    resultType: FormulaColumnRef['resultType'] = 'number',
+  ): FormulaColumnRef => ({ key, label: key, expression, resultType })
+
+  it('computes a column for a row', () => {
+    const set = compileFormulaColumns([ref('formula__margin', 'revenue - cost')], fields)
+    const results = evaluateFormulaRow(set, { revenue: 1000, cost: 620 })
+    expect(results.get('formula__margin')).toEqual({ state: 'ok', value: 380 })
+  })
+
+  it('evaluates a dependent formula after the one it reads', () => {
+    // Declared out of dependency order on purpose.
+    const set = compileFormulaColumns(
+      [
+        ref('formula__pct', 'formula__margin / revenue * 100'),
+        ref('formula__margin', 'revenue - cost'),
+      ],
+      fields,
+    )
+    expect(set.order.map((c) => c.ref.key)).toEqual(['formula__margin', 'formula__pct'])
+    const results = evaluateFormulaRow(set, { revenue: 1000, cost: 900 })
+    expect(results.get('formula__pct')).toEqual({ state: 'ok', value: 10 })
+  })
+
+  it('propagates an upstream error instead of inventing a fresh one', () => {
+    const set = compileFormulaColumns(
+      [ref('formula__a', 'revenue / qty'), ref('formula__b', 'formula__a + 1')],
+      fields,
+    )
+    const results = evaluateFormulaRow(set, { revenue: 10, qty: 0 })
+    expect((results.get('formula__b') as Extract<FormulaCellResult, { state: 'error' }>).issue.code).toBe(
+      'divide_by_zero',
+    )
+  })
+
+  it('keeps a broken definition inside its own column', () => {
+    const set = compileFormulaColumns(
+      [ref('formula__bad', 'revenue - nope'), ref('formula__good', 'revenue - cost')],
+      fields,
+    )
+    const results = evaluateFormulaRow(set, { revenue: 1000, cost: 620 })
+    expect(results.get('formula__good')).toEqual({ state: 'ok', value: 380 })
+    const bad = results.get('formula__bad') as Extract<FormulaCellResult, { state: 'error' }>
+    expect(bad.state).toBe('error')
+    expect(bad.issue.code).toBe('unknown_field')
+  })
+
+  it('refuses a cycle at compile time rather than recursing at render time', () => {
+    const set = compileFormulaColumns([ref('formula__a', 'formula__a + 1')], fields)
+    expect(set.order).toHaveLength(0)
+    expect(set.invalid.get('formula__a')?.code).toBe('cycle')
+    expect(() => evaluateFormulaRow(set, { revenue: 1 })).not.toThrow()
+  })
+
+  it('records only genuine inputs as cache keys, not other formula columns', () => {
+    const set = compileFormulaColumns(
+      [
+        ref('formula__margin', 'revenue - cost'),
+        ref('formula__pct', 'formula__margin / revenue'),
+      ],
+      fields,
+    )
+    expect(set.inputKeys.sort()).toEqual(['cost', 'revenue'])
+  })
+})
+
+describe('createFormulaRowEvaluator', () => {
+  const set = compileFormulaColumns(
+    [{ key: 'formula__margin', label: 'Margin', expression: 'revenue - cost', resultType: 'number' }],
+    fields,
+  )
+
+  it('returns the cached result while the inputs are unchanged', () => {
+    const evaluate = createFormulaRowEvaluator(set)
+    const row = { revenue: 1000, cost: 620, ref_no: 'A' }
+    const first = evaluate(row)
+    expect(evaluate(row)).toBe(first)
+  })
+
+  it('recomputes when an input is mutated IN PLACE, which is what the cell store does', () => {
+    const evaluate = createFormulaRowEvaluator(set)
+    const row: Record<string, unknown> = { revenue: 1000, cost: 620 }
+    expect(evaluate(row).get('formula__margin')).toEqual({ state: 'ok', value: 380 })
+    row.cost = 500
+    expect(evaluate(row).get('formula__margin')).toEqual({ state: 'ok', value: 500 })
+  })
+
+  it('does not recompute when an unrelated field is mutated', () => {
+    const evaluate = createFormulaRowEvaluator(set)
+    const row: Record<string, unknown> = { revenue: 1000, cost: 620, ref_no: 'A' }
+    const first = evaluate(row)
+    row.ref_no = 'B'
+    expect(evaluate(row)).toBe(first)
+  })
+
+  it('tolerates a missing row', () => {
+    const evaluate = createFormulaRowEvaluator(set)
+    expect(evaluate(undefined as unknown as Record<string, unknown>).size).toBe(0)
+  })
+})
+
+describe('evaluateExpression', () => {
+  it('drives the editor preview in one call', () => {
+    expect(evaluateExpression('revenue - cost', { revenue: 10, cost: 4 }, fields)).toEqual({
+      state: 'ok',
+      value: 6,
+    })
+  })
+
+  it('returns the syntax issue rather than throwing while the user types', () => {
+    const result = evaluateExpression('revenue -', {}, fields)
+    expect(result.state).toBe('error')
+    if (result.state !== 'error') return
+    expect(result.issue.code).toBe('syntax')
+  })
+})