@freighttech/ui 0.13.18

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

@@ -0,0 +1,226 @@
+import { evaluateAst } from '../formula/evaluate'
+import { parseFormula } from '../formula/parse'
+import {
+  FORMULA_FUNCTIONS,
+  FORMULA_FUNCTION_NAMES,
+  FORMULA_FUNCTION_SIGNATURES,
+  lookupFormulaFunction,
+} from '../formula/functions'
+import type { FormulaValue } from '../formula/types'
+
+// One assertion per function, plus the blank-handling rule each one commits to.
+// These are the cheapest tests in the codebase and they guard the most
+// expensive class of bug: a number that is wrong but plausible.
+
+const NOW = new Date(2026, 7, 3) // 2026-08-03, local
+
+function call(expression: string, row: Record<string, unknown> = {}): FormulaValue {
+  const parsed = parseFormula(expression)
+  if (!parsed.ok) throw new Error(`unparsable: ${expression} — ${parsed.issue.message}`)
+  const result = evaluateAst(parsed.ast, row, { now: () => NOW })
+  if (!result.ok) throw new Error(`expected a value, got ${result.issue.code}`)
+  return result.value
+}
+
+function callError(expression: string, row: Record<string, unknown> = {}): string {
+  const parsed = parseFormula(expression)
+  if (!parsed.ok) return parsed.issue.code
+  const result = evaluateAst(parsed.ast, row, { now: () => NOW })
+  if (result.ok) throw new Error(`expected an error, got ${String(result.value)}`)
+  return result.issue.code
+}
+
+describe('the registry', () => {
+  it('exposes every function under a canonical upper-case name', () => {
+    for (const name of FORMULA_FUNCTION_NAMES) {
+      expect(FORMULA_FUNCTIONS[name].name).toBe(name)
+      expect(name).toBe(name.toUpperCase())
+    }
+  })
+
+  it('looks functions up case-insensitively', () => {
+    expect(lookupFormulaFunction('round')?.name).toBe('ROUND')
+    expect(lookupFormulaFunction('Round')?.name).toBe('ROUND')
+    expect(lookupFormulaFunction('nope')).toBeUndefined()
+  })
+
+  it('gives every function a signature for the editor list', () => {
+    expect(FORMULA_FUNCTION_SIGNATURES).toHaveLength(FORMULA_FUNCTION_NAMES.length)
+    for (const entry of FORMULA_FUNCTION_SIGNATURES) {
+      expect(entry.signature).toContain(entry.name)
+    }
+  })
+
+  it('covers the freight cases the spec names', () => {
+    for (const name of ['IF', 'COALESCE', 'ROUND', 'ABS', 'MIN', 'MAX', 'DAYS_BETWEEN', 'CONCAT', 'UPPER', 'LOWER', 'LEN', 'IS_EMPTY']) {
+      expect(FORMULA_FUNCTION_NAMES).toContain(name)
+    }
+  })
+})
+
+describe('logic', () => {
+  it('IF picks a branch and evaluates only that branch', () => {
+    expect(call('IF(a > 1, "big", "small")', { a: 2 })).toBe('big')
+    expect(call('IF(a > 1, "big", "small")', { a: 0 })).toBe('small')
+  })
+
+  it('IF treats a blank condition as false', () => {
+    expect(call('IF(a, 1, 2)', { a: null })).toBe(2)
+  })
+
+  it('IF does not evaluate the branch it did not take', () => {
+    // The untaken branch divides by zero; taking it would error.
+    expect(call('IF(a > 1, 10, 1 / 0)', { a: 5 })).toBe(10)
+  })
+
+  it('IFERROR replaces an error with a fallback', () => {
+    expect(call('IFERROR(a / b, 0)', { a: 1, b: 0 })).toBe(0)
+    expect(call('IFERROR(a / b, 0)', { a: 10, b: 2 })).toBe(5)
+  })
+
+  it('AND and OR short-circuit and skip the rest', () => {
+    expect(call('AND(TRUE, FALSE, 1 / 0 > 0)')).toBe(false)
+    expect(call('OR(FALSE, TRUE, 1 / 0 > 0)')).toBe(true)
+    expect(call('AND(TRUE, TRUE)')).toBe(true)
+    expect(call('OR(FALSE, FALSE)')).toBe(false)
+  })
+
+  it('NOT inverts, and stays blank on a blank', () => {
+    expect(call('NOT(TRUE)')).toBe(false)
+    expect(call('NOT(a)', { a: null })).toBeNull()
+  })
+
+  it('IS_EMPTY sees blanks and empty strings, and only those', () => {
+    expect(call('IS_EMPTY(a)', { a: null })).toBe(true)
+    expect(call('IS_EMPTY(a)', {})).toBe(true)
+    expect(call('IS_EMPTY(a)', { a: '' })).toBe(true)
+    expect(call('IS_EMPTY(a)', { a: 0 })).toBe(false)
+    expect(call('IS_EMPTY(a)', { a: 'x' })).toBe(false)
+  })
+
+  it('COALESCE returns the first present value', () => {
+    expect(call('COALESCE(a, b, 0)', { a: null, b: 7 })).toBe(7)
+    expect(call('COALESCE(a, b, 0)', { a: null, b: null })).toBe(0)
+    expect(call('COALESCE(a, b)', { a: null, b: null })).toBeNull()
+  })
+})
+
+describe('maths', () => {
+  it('ABS, CEILING, FLOOR, SQRT', () => {
+    expect(call('ABS(-4)')).toBe(4)
+    expect(call('CEILING(1.2)')).toBe(2)
+    expect(call('FLOOR(1.8)')).toBe(1)
+    expect(call('SQRT(9)')).toBe(3)
+    expect(callError('SQRT(-1)')).toBe('type_mismatch')
+  })
+
+  it('ROUND rounds half away from zero, as Excel does', () => {
+    expect(call('ROUND(2.5)')).toBe(3)
+    expect(call('ROUND(-2.5)')).toBe(-3)
+    expect(call('ROUND(1.005, 2)')).toBe(1.01)
+    expect(call('ROUND(1234.5678, 2)')).toBe(1234.57)
+    expect(call('ROUND(1234.5678, 0)')).toBe(1235)
+  })
+
+  it('MIN, MAX, SUM and AVERAGE skip blanks rather than treating them as zero', () => {
+    expect(call('MIN(3, 1, 2)')).toBe(1)
+    expect(call('MAX(3, 1, 2)')).toBe(3)
+    expect(call('SUM(1, 2, 3)')).toBe(6)
+    expect(call('AVERAGE(2, 4)')).toBe(3)
+    expect(call('MIN(a, 5)', { a: null })).toBe(5)
+    expect(call('SUM(a, 5)', { a: null })).toBe(5)
+    expect(call('AVERAGE(a, 4)', { a: null })).toBe(4)
+  })
+
+  it('every-argument-blank yields blank, not zero', () => {
+    expect(call('SUM(a, b)', { a: null, b: null })).toBeNull()
+  })
+
+  it('POWER and MOD', () => {
+    expect(call('POWER(2, 10)')).toBe(1024)
+    expect(call('MOD(7, 3)')).toBe(1)
+    expect(callError('MOD(7, 0)')).toBe('divide_by_zero')
+  })
+})
+
+describe('text', () => {
+  it('CONCAT joins and drops blanks', () => {
+    expect(call('CONCAT("A", "-", 1)')).toBe('A-1')
+    expect(call('CONCAT(a, "B")', { a: null })).toBe('B')
+  })
+
+  it('UPPER, LOWER, TRIM, LEN', () => {
+    expect(call('UPPER("abc")')).toBe('ABC')
+    expect(call('LOWER("ABC")')).toBe('abc')
+    expect(call('TRIM("  x  ")')).toBe('x')
+    expect(call('LEN("abcd")')).toBe(4)
+  })
+
+  it('LEFT and RIGHT', () => {
+    expect(call('LEFT("MSCU7234561", 4)')).toBe('MSCU')
+    expect(call('RIGHT("MSCU7234561", 7)')).toBe('7234561')
+    expect(call('RIGHT("abc", 0)')).toBe('')
+  })
+
+  it('CONTAINS is case-insensitive, matching how people search', () => {
+    expect(call('CONTAINS("Gdańsk terminal", "TERMINAL")')).toBe(true)
+    expect(call('CONTAINS("Gdańsk terminal", "hamburg")')).toBe(false)
+  })
+
+  it('TEXT and VALUE convert across the boundary', () => {
+    expect(call('TEXT(12.5)')).toBe('12.5')
+    expect(call('VALUE("12.5")')).toBe(12.5)
+    expect(callError('VALUE("abc")')).toBe('type_mismatch')
+  })
+
+  it('text functions stay blank on a blank rather than returning ""', () => {
+    expect(call('UPPER(a)', { a: null })).toBeNull()
+    expect(call('LEN(a)', { a: null })).toBeNull()
+  })
+})
+
+describe('dates', () => {
+  it('TODAY uses the injected clock and is truncated to the day', () => {
+    expect(call('TODAY()')).toEqual(new Date(2026, 7, 3))
+  })
+
+  it('DAYS_BETWEEN counts whole days and is signed', () => {
+    expect(call('DAYS_BETWEEN(a, b)', { a: '2026-01-01', b: '2026-01-31' })).toBe(30)
+    expect(call('DAYS_BETWEEN(a, b)', { a: '2026-01-31', b: '2026-01-01' })).toBe(-30)
+  })
+
+  it('DAYS_BETWEEN ignores the time of day', () => {
+    expect(
+      call('DAYS_BETWEEN(a, b)', { a: new Date(2026, 0, 1, 23), b: new Date(2026, 0, 2, 1) }),
+    ).toBe(1)
+  })
+
+  it('DATE_ADD shifts by whole days', () => {
+    expect(call('DATE_ADD(a, 10)', { a: '2026-01-25' })).toEqual(new Date(2026, 1, 4))
+  })
+
+  it('YEAR, MONTH and DAY are 1-based for the month, matching Excel', () => {
+    expect(call('YEAR(a)', { a: '2026-08-03' })).toBe(2026)
+    expect(call('MONTH(a)', { a: '2026-08-03' })).toBe(8)
+    expect(call('DAY(a)', { a: '2026-08-03' })).toBe(3)
+  })
+
+  it('rejects a value that is not a date rather than guessing a locale', () => {
+    expect(callError('YEAR(a)', { a: '03/08/2026' })).toBe('type_mismatch')
+  })
+
+  it('stays blank on a blank date', () => {
+    expect(call('DAYS_BETWEEN(a, b)', { a: null, b: '2026-01-01' })).toBeNull()
+  })
+})
+
+describe('arity is enforced at evaluation too, not only at definition', () => {
+  it('rejects too few and too many arguments', () => {
+    expect(callError('ABS()')).toBe('arity')
+    expect(callError('ABS(1, 2)')).toBe('arity')
+  })
+
+  it('rejects an unknown function', () => {
+    expect(callError('VLOOKUP(1)')).toBe('unknown_function')
+  })
+})

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

@@ -0,0 +1,92 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+// A user-authored expression evaluated through `eval` or `new Function` is
+// arbitrary JavaScript running against tenant data in every viewer's browser.
+// The spec rates that Critical, and the mitigation is that the evaluator walks
+// the AST and nothing else.
+//
+// The spec asked for an eslint rule. `packages/ui` has no eslint config and the
+// root `yarn lint` never reaches these files, so the ban is enforced here
+// instead: a source scan that fails the unit suite the moment anyone adds a
+// dynamic-code escape hatch to the formula surface.
+
+const ROOT = path.resolve(__dirname, '..')
+
+/** Every source file that participates in parsing or evaluating a formula. */
+function formulaSourceFiles(): string[] {
+  const formulaDir = path.join(ROOT, 'formula')
+  const files = fs
+    .readdirSync(formulaDir)
+    .filter((f) => f.endsWith('.ts') || f.endsWith('.tsx'))
+    .map((f) => path.join(formulaDir, f))
+  return [
+    ...files,
+    path.join(ROOT, 'utils', 'formulaColumns.tsx'),
+    path.join(ROOT, 'components', 'ConfigureViewFormulas.tsx'),
+  ]
+}
+
+/**
+ * Every way to reach the JavaScript compiler at runtime. `setTimeout`/
+ * `setInterval` are included because both accept a code string.
+ */
+const FORBIDDEN: { label: string; pattern: RegExp }[] = [
+  { label: 'eval(', pattern: /\beval\s*\(/ },
+  { label: 'new Function', pattern: /\bnew\s+Function\s*\(/ },
+  { label: 'Function constructor', pattern: /\bFunction\s*\(\s*['"`]/ },
+  { label: 'GeneratorFunction / AsyncFunction', pattern: /(Generator|Async)Function/ },
+  { label: 'setTimeout with a code string', pattern: /setTimeout\s*\(\s*['"`]/ },
+  { label: 'setInterval with a code string', pattern: /setInterval\s*\(\s*['"`]/ },
+  { label: 'import()', pattern: /[^.\w]import\s*\(/ },
+  { label: 'require()', pattern: /\brequire\s*\(/ },
+]
+
+describe('the formula surface never reaches the JavaScript compiler', () => {
+  const files = formulaSourceFiles()
+
+  it('scans a non-empty set of files (so a rename cannot silently disable this test)', () => {
+    expect(files.length).toBeGreaterThanOrEqual(7)
+    for (const file of files) expect(fs.existsSync(file)).toBe(true)
+  })
+
+  it.each(files.map((f) => [path.relative(ROOT, f), f]))(
+    '%s contains no dynamic-code escape hatch',
+    (_name, file) => {
+      const source = fs.readFileSync(file, 'utf8')
+      for (const { label, pattern } of FORBIDDEN) {
+        expect({ file: path.relative(ROOT, file), found: pattern.test(source), label }).toEqual({
+          file: path.relative(ROOT, file),
+          found: false,
+          label,
+        })
+      }
+    },
+  )
+
+  it('adds no formula-parsing dependency — HyperFormula is GPLv3 and excluded', () => {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.resolve(ROOT, '../../..', 'package.json'), 'utf8'),
+    ) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+    const declared = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })
+    for (const banned of [
+      'hyperformula',
+      'fast-formula-parser',
+      '@sheetxl/formulas',
+      'formula.js',
+      'hot-formula-parser',
+      '@univerjs/engine-formula',
+    ]) {
+      expect(declared).not.toContain(banned)
+    }
+  })
+
+  it('keeps the formula engine free of React and of the host framework', () => {
+    const formulaDir = path.join(ROOT, 'formula')
+    for (const file of fs.readdirSync(formulaDir)) {
+      const source = fs.readFileSync(path.join(formulaDir, file), 'utf8')
+      expect(source).not.toContain("from 'react'")
+      expect(source).not.toContain("from '@open-mercato/")
+    }
+  })
+})

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

@@ -0,0 +1,233 @@
+import { collectFieldRefs, parseFormula, tokenize } from '../formula/parse'
+import type { FormulaAst } from '../formula/types'
+
+// The parser is the one place where a precedence slip produces a number that is
+// wrong but plausible, so these assertions are on the AST shape rather than on
+// an evaluated result — a wrong tree is caught here instead of being explained
+// away downstream.
+
+function ast(source: string): FormulaAst {
+  const result = parseFormula(source)
+  if (!result.ok) throw new Error(`expected a parse, got ${result.issue.message}`)
+  return result.ast
+}
+
+function issue(source: string) {
+  const result = parseFormula(source)
+  if (result.ok) throw new Error(`expected a syntax error for ${source}`)
+  return result.issue
+}
+
+describe('tokenize', () => {
+  it('reads numbers, strings, identifiers and bracketed fields', () => {
+    const tokens = tokenize('12.5 + "a b" + total_cost + [Unit price]')
+    expect(tokens.map((t) => t.type)).toEqual([
+      'number',
+      'punct',
+      'string',
+      'punct',
+      'ident',
+      'punct',
+      'field',
+      'eof',
+    ])
+    expect(tokens[0].value).toBe(12.5)
+    expect(tokens[2].value).toBe('a b')
+    expect(tokens[6].text).toBe('Unit price')
+  })
+
+  it('prefers two-character operators over one-character ones', () => {
+    expect(tokenize('a >= b').map((t) => t.text)).toEqual(['a', '>=', 'b', ''])
+    expect(tokenize('a && b').map((t) => t.text)).toEqual(['a', '&&', 'b', ''])
+    expect(tokenize('a & b').map((t) => t.text)).toEqual(['a', '&', 'b', ''])
+  })
+
+  it('honours backslash escapes inside strings', () => {
+    expect(tokenize('"say \\"hi\\""')[0].value).toBe('say "hi"')
+  })
+})
+
+describe('parseFormula — literals and references', () => {
+  it('parses each literal kind', () => {
+    expect(ast('42')).toEqual({ k: 'lit', v: 42 })
+    expect(ast("'text'")).toEqual({ k: 'lit', v: 'text' })
+    expect(ast('TRUE')).toEqual({ k: 'lit', v: true })
+    expect(ast('false')).toEqual({ k: 'lit', v: false })
+    expect(ast('NULL')).toEqual({ k: 'lit', v: null })
+  })
+
+  it('parses bare and bracketed field references', () => {
+    expect(ast('revenue')).toEqual({ k: 'field', name: 'revenue' })
+    expect(ast('[Unit price]')).toEqual({ k: 'field', name: 'Unit price' })
+    expect(ast('lookup__contractor__tax_id')).toEqual({
+      k: 'field',
+      name: 'lookup__contractor__tax_id',
+    })
+  })
+})
+
+describe('parseFormula — precedence', () => {
+  it('binds * tighter than +', () => {
+    expect(ast('1 + 2 * 3')).toEqual({
+      k: 'bin',
+      op: '+',
+      l: { k: 'lit', v: 1 },
+      r: { k: 'bin', op: '*', l: { k: 'lit', v: 2 }, r: { k: 'lit', v: 3 } },
+    })
+  })
+
+  it('honours explicit parentheses over precedence', () => {
+    expect(ast('(1 + 2) * 3')).toEqual({
+      k: 'bin',
+      op: '*',
+      l: { k: 'bin', op: '+', l: { k: 'lit', v: 1 }, r: { k: 'lit', v: 2 } },
+      r: { k: 'lit', v: 3 },
+    })
+  })
+
+  it('is left-associative for - and /', () => {
+    expect(ast('10 - 3 - 2')).toEqual({
+      k: 'bin',
+      op: '-',
+      l: { k: 'bin', op: '-', l: { k: 'lit', v: 10 }, r: { k: 'lit', v: 3 } },
+      r: { k: 'lit', v: 2 },
+    })
+  })
+
+  it('binds & (concat) tighter than comparison, as Excel does', () => {
+    expect(ast("a & b = 'x'")).toEqual({
+      k: 'bin',
+      op: '=',
+      l: { k: 'bin', op: 'concat', l: { k: 'field', name: 'a' }, r: { k: 'field', name: 'b' } },
+      r: { k: 'lit', v: 'x' },
+    })
+  })
+
+  it('binds comparison tighter than AND, and AND tighter than OR', () => {
+    expect(ast('a > 1 AND b < 2 OR c')).toEqual({
+      k: 'bin',
+      op: '||',
+      l: {
+        k: 'bin',
+        op: '&&',
+        l: { k: 'bin', op: '>', l: { k: 'field', name: 'a' }, r: { k: 'lit', v: 1 } },
+        r: { k: 'bin', op: '<', l: { k: 'field', name: 'b' }, r: { k: 'lit', v: 2 } },
+      },
+      r: { k: 'field', name: 'c' },
+    })
+  })
+
+  it('applies unary minus before multiplication', () => {
+    expect(ast('-a * 2')).toEqual({
+      k: 'bin',
+      op: '*',
+      l: { k: 'neg', e: { k: 'field', name: 'a' } },
+      r: { k: 'lit', v: 2 },
+    })
+  })
+
+  it('normalises the alternate spellings of the comparison operators', () => {
+    expect(ast('a <> b')).toEqual({
+      k: 'bin',
+      op: '!=',
+      l: { k: 'field', name: 'a' },
+      r: { k: 'field', name: 'b' },
+    })
+    expect(ast('a == b')).toEqual({
+      k: 'bin',
+      op: '=',
+      l: { k: 'field', name: 'a' },
+      r: { k: 'field', name: 'b' },
+    })
+  })
+})
+
+describe('parseFormula — calls', () => {
+  it('upper-cases the function name so IF and if are one function', () => {
+    expect(ast('if(a, 1, 2)')).toEqual({
+      k: 'call',
+      fn: 'IF',
+      args: [{ k: 'field', name: 'a' }, { k: 'lit', v: 1 }, { k: 'lit', v: 2 }],
+    })
+  })
+
+  it('parses a zero-argument call', () => {
+    expect(ast('TODAY()')).toEqual({ k: 'call', fn: 'TODAY', args: [] })
+  })
+
+  it('parses nested calls', () => {
+    expect(ast('ROUND(SUM(a, b), 2)')).toEqual({
+      k: 'call',
+      fn: 'ROUND',
+      args: [
+        { k: 'call', fn: 'SUM', args: [{ k: 'field', name: 'a' }, { k: 'field', name: 'b' }] },
+        { k: 'lit', v: 2 },
+      ],
+    })
+  })
+
+  it('reads AND as a function when it is followed by "(" and as an operator otherwise', () => {
+    expect(ast('AND(a, b)')).toEqual({
+      k: 'call',
+      fn: 'AND',
+      args: [{ k: 'field', name: 'a' }, { k: 'field', name: 'b' }],
+    })
+    expect(ast('a AND b')).toEqual({
+      k: 'bin',
+      op: '&&',
+      l: { k: 'field', name: 'a' },
+      r: { k: 'field', name: 'b' },
+    })
+  })
+
+  it('lowers NOT to the library function, keeping the AST to five node kinds', () => {
+    expect(ast('NOT a')).toEqual({ k: 'call', fn: 'NOT', args: [{ k: 'field', name: 'a' }] })
+    expect(ast('!a')).toEqual({ k: 'call', fn: 'NOT', args: [{ k: 'field', name: 'a' }] })
+  })
+})
+
+describe('parseFormula — syntax errors', () => {
+  it('never throws; a malformed formula is a returned issue', () => {
+    expect(() => parseFormula('((((')).not.toThrow()
+    expect(parseFormula('((((').ok).toBe(false)
+  })
+
+  it('reports the offending token and its position', () => {
+    const err = issue('a + ')
+    expect(err.code).toBe('syntax')
+    expect(err.params?.token).toBe('end of formula')
+    expect(err.position).toBe(4)
+  })
+
+  it('rejects an unknown character', () => {
+    expect(issue('2 ^ 3').params?.token).toBe('^')
+  })
+
+  it('rejects an unterminated string and an unterminated bracket', () => {
+    expect(issue('"abc').code).toBe('syntax')
+    expect(issue('[abc').code).toBe('syntax')
+    expect(issue('[]').code).toBe('syntax')
+  })
+
+  it('rejects a chained comparison rather than silently mis-reading it', () => {
+    expect(issue('a < b < c').code).toBe('syntax')
+  })
+
+  it('rejects trailing input after a complete expression', () => {
+    expect(issue('1 2').code).toBe('syntax')
+  })
+
+  it('treats an empty expression as a syntax issue, not a crash', () => {
+    expect(issue('   ').code).toBe('syntax')
+  })
+})
+
+describe('collectFieldRefs', () => {
+  it('collects every reference once, in first-seen order', () => {
+    expect(collectFieldRefs(ast('IF(a > b, a - b, [Other] & a)'))).toEqual(['a', 'b', 'Other'])
+  })
+
+  it('returns nothing for an expression over literals only', () => {
+    expect(collectFieldRefs(ast('1 + 2'))).toEqual([])
+  })
+})