Developer Guide

Getting Started with nix

For instructions on installing nix, see TODO.

To develop within this repository, we recommend using a development shell defined in flake.nix. In this way, you will use applications pinned to same version that other developers and the CI use.

For example, from the project’s root directory, launch the project’s default shell using:

nix develop .

To launch a shell with the haskell toolchain loaded:

nix develop .#haskell

After launching a nix shell, you’re in a bash shell with the appropriate applications in your path.

As of 2022-04-12, cabal build all fails in the project’s nix Haskell shell on an M1 Mac (it works on the CI’s linux machine). For now, use your locally installed versions of ghc and cabal.

Running repo checks

Run the same checks that the CI uses locally with

nix build .#check.aarch64-darwin

replacing aarch64-darwin with your system as needed.

Notable Indirections

This sections tries to document where and why the structure of certain parts of the repository may not be straightfoward.

  • Tests for models are not automatically created in the fact-models library. Model creators should create a Test module for their model, and add those tests to the main Test module.

  • This repo uses ormolu for Haskell formatting. Other repos such as asclepias use brittany, but as of 2022-04-22 brittany yields errors likely due to incompatability with template haskell.

  • The eventline shape is defined for Rust in this repo, but as of 2022-04-22, the same shapes in Haskell are defined in the event-data-theory package in asclepias.

  • The build-fragments application (see flake.nix in project root) creates a dhall file than be used to check the integrity of each Fact.dhall (or Model.dhall) file. This is checked by the check-fragments.sh check (see flake.nix) with dhall freeze $1 --check --all. This also serves to check that the fragments are up-to-date assuming that the fragments are only created by build-fragments and not edited otherwise.

Tests

An important part of this repository are the integration tests that ensure that application logic is correct and that data can be marshalled to/from applications as appropriate.

This page documents checks done in this repo and where they are found.

Table 1. Tests
Description Notes Implemented

Serialization of facts and models in Haskell, Dhall, and JSON

See fact-models/internal/Tests.hs module for code that generates tests. The makeFactIOTest (or makeFactIOTestWithDepth) function test the following properties:

  1. Haskell → dhall → Haskell === Haskell

  2. dhall → json → Haskell === Haskell

  3. dhall → json → Haskell === Haskell ← json ← Haskell

  4. dhall → Haskell → json === json ← dhall

The testFactExamplesJSON (testModelExamplesJSON) function tests that:

  1. Fact-examples.json → Haskell (Model-examples.json → Haskell)

See fact-models/src/Models/ClaimsModel/Tests.hs for example usage.

Each model needs to call the test functions in a test module.

Yes, though see note.

Eventlines values produced by upstream processes can be marshalled to/from Haskell applications

No

Versioning

Versioning of fact-models and other packages in this repository follow semantic versioning (MAJOR.MINOR.PATCH), where you increment:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner
PATCH version when you make backwards compatible bug fixes

In particular, adding new facts or models typically only requires a MINOR update, while changing the shape of existing facts or models should trigger a MAJOR update. Bug fixes to the library functions should only trigger a PATCH update.