ivx research

ivx research Difflicit Analysis engines

Analysis engines

An analysis engine is what Analyze runs. You pick two artifacts (or two versions of one), the engine analyzes how they changed, and its analysis becomes a diffmd note in the project.

Engines differ in how far they go: what changed in the code, how the behaviour changed, how the change shows up across environments. Each is free to go as deep as its makers want, and to be open source or proprietary, free or paid.

EngineWhat it doesLicenseGet it
Difflicit patternsPredicts what a change was about from the patterns fixes leave in a diff, without AI (Analyze).GPL-3.0Built in
ViperWrites up the visual changes: what changed where, file by file and function by function.MITbrew install ivxlabs/tap/viper
HyperViperThe full version of Viper.ProprietaryComing

Engines are command-line tools

Every engine except the built-in one is a program you run from a terminal, and it gives you a diffmd file. You don't need Difflicit for that:

viper old/libfoo new/libfoo -o analysis.diffmd

Difflicit is the other way to use it. It finds the engine on your computer, runs it on the two artifacts you picked, and opens the analysis as a note next to their diff, where you can check it against the patch and edit it block by block. The engine works the same either way. Use whichever suits the job: the command line for scripts and CI, Difflicit for reading and writing up a change.

There's no store or registry. You install engines the way you install any command-line tool: with Homebrew, a download from the engine's maker, or by building it yourself.

Using engines in Difflicit

In the desktop app, open Analyze. Its Engine menu lists the engines installed on this computer, the built-in one first, and it remembers the one you used last. Pick one, then Analyze: the engine's analysis is saved in the project as analysis-<artifact>-<before>-to-<after>.diffmd and opened.

Manage engines… (in the Analyze dialog, or Analysis engines… in the command palette) lists every engine Difflicit knows of:

  • Installed engines, with their version, license and description.
  • Not installed ones Difflicit offers by default, with the command that installs them and a button to copy it. Install from a terminal, then reopen the dialog.
  • Engines you added. To use an engine Difflicit doesn't list, type its command (acme-engine) or its path, or Browse… to its program, and Add. Difflicit asks the program what it is first, and adds it only if it answers as an engine it can talk to. The trash icon takes it off the list; it stays installed.

Difflicit looks for engines on your PATH. It also looks in Homebrew's and Cargo's folders (/opt/homebrew/bin, /usr/local/bin, /home/linuxbrew/.linuxbrew/bin, ~/.cargo/bin, ~/.local/bin), because apps opened from the Dock or Finder don't get your shell's PATH.

If an analysis fails, Difflicit shows what the engine said went wrong (a missing tool, a licence to activate). An analysis that runs for over an hour is stopped.

An instance can choose which engines it offers by default, and how to install each, under engines in difflicit.config.json (Run your own instance).

Making your own

An engine is any program that answers two command-line options, --about and --difflicit. It can be written in any language, released under any license, and do its analysis anywhere, on your computer or on a server. See Writing an engine. The quickest start is to fork Viper, which is MIT-licensed for exactly that.