feat: support searching where value is unknown (#75)

* feat: support searching where value is unknown

Adds minimal support for 3-valued logic. Formula types support
arbitrarily many extended types with the default (X = never) type,
but parsing and evaluating is currently only well-defined for value
types that extend (boolean | null).

Note that we're using null to represent unknown here in part so that
helpers like

    atom(property, value = true)

can distinguish between being called with an unknown and being called
without providing the default argument.

Fixes #70

* fix: formula summary display for unknowns

* chore: restore test coverage thresholds

Author: jamesdabbs

packages/core/src/Formula.ts

@@ -31,37 +31,40 @@ const orSchema = <P>(p: z.ZodSchema<P>) =>
 export const formulaSchema = <P>(p: z.ZodSchema<P>): z.ZodSchema<F<P>> =>
   z.union([atomSchema(p), andSchema(p), orSchema(p)])
 
-export interface Atom<P> {
+export interface Atom<P, X = never> {
   kind: 'atom'
   property: P
-  value: boolean
+  value: boolean | X
 }
 
-export interface And<P> {
+export interface And<P, X = never> {
   kind: 'and'
-  subs: Formula<P>[]
+  subs: Formula<P, X>[]
 }
 
-export interface Or<P> {
+export interface Or<P, X = never> {
   kind: 'or'
-  subs: Formula<P>[]
+  subs: Formula<P, X>[]
 }
 
-export type Formula<P> = And<P> | Or<P> | Atom<P>
+export type Formula<P, X = never> = And<P, X> | Or<P, X> | Atom<P, X>
 
-export function and<P>(...subs: Formula<P>[]): And<P> {
+export function and<P, X = never>(...subs: Formula<P, X>[]): And<P, X> {
   return { kind: 'and', subs: subs }
 }
 
-export function or<P>(...subs: Formula<P>[]): Or<P> {
+export function or<P, X = never>(...subs: Formula<P, X>[]): Or<P, X> {
   return { kind: 'or', subs: subs }
 }
 
-export function atom<P>(p: P, v = true): Atom<P> {
-  return { kind: 'atom', property: p, value: v }
+export function atom<P, X = never>(
+  property: P,
+  value: boolean | X = true,
+): Atom<P, X> {
+  return { kind: 'atom', property, value }
 }
 
-export function properties<P>(f: Formula<P>): Set<P> {
+export function properties<P, X>(f: Formula<P, X>): Set<P> {
   switch (f.kind) {
     case 'atom':
       return new Set([f.property])
@@ -94,10 +97,10 @@ export function negate<P>(formula: Formula<P>): Formula<P> {
   }
 }
 
-export function map<P, Q>(
-  func: (p: Atom<P>) => Atom<Q>,
-  formula: Formula<P>,
-): Formula<Q> {
+export function map<P, Q, X = never>(
+  func: (p: Atom<P, X>) => Atom<Q, X>,
+  formula: Formula<P, X>,
+): Formula<Q, X> {
   switch (formula.kind) {
     case 'atom':
       return func(formula)
@@ -109,32 +112,38 @@ export function map<P, Q>(
   }
 }
 
-export function mapProperty<P, Q>(
+export function mapProperty<P, Q, X = never>(
   func: (p: P) => Q,
-  formula: Formula<P>,
-): Formula<Q> {
-  function mapAtom(a: Atom<P>): Atom<Q> {
+  formula: Formula<P, X>,
+): Formula<Q, X> {
+  function mapAtom(a: Atom<P, X>): Atom<Q, X> {
     return { ...a, property: func(a.property) }
   }
-  return map<P, Q>(mapAtom, formula)
+  return map<P, Q, X>(mapAtom, formula)
 }
 
-export function compact<P>(f: Formula<P | undefined>): Formula<P> | undefined {
-  return properties(f).has(undefined) ? undefined : (f as Formula<P>)
+export function compact<P, X>(
+  f: Formula<P | undefined, X>,
+): Formula<P, X> | undefined {
+  return properties(f).has(undefined) ? undefined : (f as Formula<P, X>)
 }
 
-export function evaluate<T>(
-  f: Formula<T>,
+export function evaluate<T, V extends boolean | null = boolean>(
+  f: Formula<T, V>,
   traits: Map<T, boolean>,
 ): boolean | undefined {
   let result: boolean | undefined
 
   switch (f.kind) {
     case 'atom':
-      if (traits.has(f.property)) {
-        return traits.get(f.property) === f.value
+      const known = traits.has(f.property)
+      if (f.value === null) {
+        return !known
       }
-      return undefined
+      if (!known) {
+        return undefined
+      }
+      return traits.get(f.property) === f.value
     case 'and':
       result = true // by default
       f.subs.forEach(sub => {
@@ -170,7 +179,7 @@ export function evaluate<T>(
   }
 }
 
-export function parse(q?: string): Formula<string> | undefined {
+export function parse(q?: string): Formula<string, null> | undefined {
   if (!q) {
     return
   }
@@ -190,19 +199,19 @@ export function parse(q?: string): Formula<string> | undefined {
   return fromJSON(parsed as any)
 }
 
-type Serialized =
+type Serialized<X = never> =
   | { and: Serialized[] }
   | { or: Serialized[] }
-  | { property: string; value: boolean }
-  | Record<string, boolean>
+  | { property: string; value: boolean | X }
+  | Record<string, boolean | X>
 
-export function fromJSON(json: Serialized): Formula<string> {
+export function fromJSON(json: Serialized): Formula<string, null> {
   if ('and' in json && typeof json.and === 'object') {
-    return and<string>(...json.and.map(fromJSON))
+    return and<string, null>(...json.and.map(fromJSON))
   } else if ('or' in json && typeof json.or === 'object') {
-    return or<string>(...json.or.map(fromJSON))
+    return or<string, null>(...json.or.map(fromJSON))
   } else if ('property' in json && typeof json.property === 'string') {
-    return atom<string>(json.property, json.value)
+    return atom<string, null>(json.property, json.value)
   }
 
   const entries = Object.entries(json)
@@ -214,7 +223,7 @@ export function fromJSON(json: Serialized): Formula<string> {
     throw `cannot cast object with non-boolean value`
   }
 
-  return atom<string>(...entries[0])
+  return atom<string, null>(...entries[0])
 }
 
 export function toJSON(f: Formula<string>): Serialized {

packages/core/src/Formula/Grammar.pegjs

@@ -13,7 +13,7 @@ Or = _ "(" _ head:Formula tail:(_ Disjunction _ Formula)+ _ ")" _ {
 Atom = mod:Modifier? _ prop:Property {
   let value;
   if (mod === '?') {
-    value = undefined
+    value = null
   } else if (mod) {
     value = false
   } else {

packages/core/test/Formula.test.ts

@@ -1,22 +1,25 @@
 import { describe, expect, it } from 'vitest'
-import * as F from '../src/Formula'
 import {
   Formula,
+  Or,
   and,
   atom,
+  compact,
   evaluate,
   fromJSON,
   negate,
   or,
+  map,
+  mapProperty,
   parse,
   properties,
   render,
   toJSON,
 } from '../src/Formula'
 
-const compound: Formula<string> = and(
-  atom('compact', true),
-  or(atom('connected', true), atom('separable', false)),
+const compound = and<string>(
+  atom('compact'),
+  or(atom('connected'), atom('separable', false)),
   atom('first countable', false),
 )
 
@@ -28,7 +31,7 @@ describe('Formula', () => {
       const f = compound
 
       expect(f.subs[0]).toEqual(atom('compact'))
-      expect((f.subs[1] as F.Or<string>).subs[1]).toEqual(
+      expect((f.subs[1] as Or<string>).subs[1]).toEqual(
         atom('separable', false),
       )
     })
@@ -70,8 +73,8 @@ describe('Formula', () => {
 
   describe('map', () => {
     it('maps over entire atoms', () => {
-      const result = F.map(
-        term => atom(term.property.slice(0, 2), !term.value),
+      const result = map(
+        term => atom<string>(term.property.slice(0, 2), !term.value),
         compound,
       )
 
@@ -81,12 +84,20 @@ describe('Formula', () => {
 
   describe('mapProperty', () => {
     it('only maps over properties', () => {
-      const result = F.mapProperty(property => property.slice(0, 2), compound)
+      const result = mapProperty(property => property.slice(0, 2), compound)
 
       expect(render_(result)).toEqual('(co ∧ (co ∨ ¬se) ∧ ¬fi)')
     })
   })
 
+  describe('compact', () => {
+    it('preserves null-valued atoms', () => {
+      const f = and(atom('A'), atom('B', null), atom('C', false))
+
+      expect(compact(f)).toEqual(f)
+    })
+  })
+
   describe('evaluate', () => {
     it('is true if all subs are true', () => {
       const traits = new Map([
@@ -109,14 +120,22 @@ describe('Formula', () => {
       expect(evaluate(compound, traits)).toEqual(false)
     })
 
-    it('is undefined if a sub is undefined', () => {
-      const traits = new Map([
-        ['compact', true],
-        ['first countable', false],
-      ])
+    const traits = new Map([
+      ['compact', true],
+      ['first countable', false],
+    ])
 
+    it('is undefined if a sub is undefined', () => {
       expect(evaluate(compound, traits)).toEqual(undefined)
     })
+
+    it('can match null', () => {
+      expect(evaluate(parse('?other')!, traits)).toEqual(true)
+    })
+
+    it('can fail to match null', () => {
+      expect(evaluate(parse('?compact')!, traits)).toEqual(false)
+    })
   })
 })
 
@@ -135,16 +154,18 @@ describe('parsing', () => {
     expect(parse('not compact')).toEqual(atom('compact', false))
   })
 
+  it('can mark properties unknown', () => {
+    expect(parse('?compact')).toEqual(atom('compact', null))
+  })
+
   it('inserts parens', () => {
     expect(parse('compact + connected + ~t_2')).toEqual(
       and(atom('compact', true), atom('connected', true), atom('t_2', false)),
     )
   })
 
   it('allows parens', () => {
-    expect(F.parse('(foo + bar)')).toEqual(
-      F.and(F.atom('foo', true), F.atom('bar', true)),
-    )
+    expect(parse('(foo + bar)')).toEqual(and(atom('foo'), atom('bar')))
   })
 
   it('handles errors with parens', () => {
@@ -183,4 +204,15 @@ describe('serialization', () => {
       expect(fromJSON(toJSON(formula))).toEqual(formula)
     })
   })
+
+  it('throws when given multiple keys', () => {
+    expect(() =>
+      fromJSON({
+        P1: true,
+        P2: false,
+      }),
+    ).toThrowError('cast')
+  })
+
+  it('throws when given multiple keys', () => {})
 })

packages/core/vite.config.ts

@@ -17,13 +17,13 @@ export default defineConfig({
   },
   test: {
     coverage: {
-      lines: 92.52,
-      branches: 95.32,
-      statements: 92.52,
-      functions: 83.33,
+      lines: 91.27,
+      branches: 94.01,
+      statements: 91.27,
+      functions: 83.55,
       skipFull: true,
       thresholdAutoUpdate: true,
-      exclude: ['src/Formula/Grammar.ts'],
+      exclude: ['src/Formula/Grammar.ts', 'test'],
     },
   },
 })

packages/viewer/src/components/Shared/Formula.svelte

@@ -4,7 +4,7 @@
   import Atom from './Formula/Atom.svelte'
   import Compound from './Formula/Compound.svelte'
 
-  export let value: Formula<Property>
+  export let value: Formula<Property, null>
   export let link = true
 </script>
 

packages/viewer/src/components/Shared/Formula/Atom.svelte

@@ -4,11 +4,11 @@
   import { Link, Typeset } from '@/components/Shared'
   import type { Property } from '@/models'
 
-  export let value: Atom<Property>
+  export let value: Atom<Property, null>
   export let link: boolean = true
 </script>
 
-{value.value ? '' : '¬'}
+{value.value === null ? '?' : value.value ? '' : '¬'}
 {#if link}
   <Link.Property property={value.property} />
 {:else}

packages/viewer/src/components/Shared/Formula/Compound.svelte

@@ -5,7 +5,7 @@
 
   import Formula from '../Formula.svelte'
 
-  export let value: And<Property> | Or<Property>
+  export let value: And<Property, null> | Or<Property, null>
   export let link = true
 
   $: connector = value.kind === 'and' ? '∧' : '∨'

packages/viewer/src/components/Shared/Formula/Input/store.ts

@@ -25,7 +25,7 @@ export function create({
   limit = 10,
 }: {
   raw: Writable<string>
-  formula: Writable<Formula<Property> | undefined>
+  formula: Writable<Formula<Property, null> | undefined>
   properties: Readable<Collection<Property>>
   limit?: number
 }): Store {
@@ -103,7 +103,7 @@ export function create({
 function resolve(
   index: Fuse<Property>,
   str: string,
-): Formula<Property> | undefined {
+): Formula<Property, null> | undefined {
   const parsed = F.parse(str)
   if (!parsed) {
     return