fletch_core #

Domain-agnostic comparison engine. Point N implementations of the same thing at the same inputs and find where they disagree.

What it does #

fletch_core gives you a framework for cross-implementation validation. You define adapters that wrap different implementations, feed them the same inputs, and fletch diffs the outputs field-by-field with configurable tolerances.

The core engine is generic — it doesn't know what you're comparing. Astrology engines, markdown renderers, math libraries, date/time parsers — anything where multiple implementations should produce the same (or close enough) results.

Concepts #

• Node tree — Output is modeled as a tree of Group (branches) and Field (leaves). Fields are typed: numeric, categorical, or ordinal.
• Adapter — Wraps an implementation. Takes an input, returns a tree. Can be in-process, a subprocess, an HTTP call — whatever.
• Tolerance — Per-field rules for what counts as "matching". Numeric fields get absolute/relative thresholds. Categorical fields can map equivalent values. Glob patterns (*, **) match tolerance rules to tree paths.
• Execution matrix — M inputs x N adapters. Every cell gets a result (success, partial, or failure).
• Comparison — Pairwise diffs across all adapter pairs. Outlier detection when 3+ adapters are present.

Usage #

import 'package:fletch_core/fletch_core.dart';

// 1. Define adapters
class MyAdapter extends SystemAdapter<String> {
  @override
  String get id => 'my_impl';
  @override
  String get name => 'My Implementation';
  @override
  bool supports(String input) => true;

  @override
  Future<AdapterResult> execute(String input) async {
    final tree = Group('root')
      ..add(Field('value', 42.0, FieldType.numeric));
    return AdapterSuccess(tree, Duration.zero);
  }
}

// 2. Set up tolerances (first match wins, dot-separated paths)
final profile = ToleranceProfile('standard', [
  ToleranceRule('root.value', NumericTolerance(0.001)),
  ToleranceRule('root.labels.*', CategoricalTolerance({'N': 'North'})),
  ToleranceRule('**', ExactMatch()),
]);

// 3. Run and compare
final engine = ExecutionEngine();
final matrix = await engine.run(['input1', 'input2'], [adapterA, adapterB]);
final result = const ComparisonEngine().compare(matrix, profile);

// 4. Report
print(const TextReporter().runSummary(result));

// Or export everything as JSON (for fletch_ui viewer)
final json = const JsonReporter().fullReport(result);
File('result.json').writeAsStringSync(jsonEncode(json));

Domain implementations #

fletch_core is the engine. Domain packages build on it:

• fletch_astro — Compares astrology calculation engines (libaditya, PyJHora, Kerykeion, and more) with process bridges to Python, C#, and other runtimes.

For guidance on building your own domain package, see Writing Adapters.

Installation #

dependencies:
  fletch_core: ^0.2.0