Revise and improve the documentation

Author: habedi

Makefile

@@ -12,11 +12,6 @@ BUILD_DIR     := zig-out
 CACHE_DIR     := .zig-cache
 DOC_SRC       := src/lib.zig
 DOC_OUT       := docs/api/
-COVERAGE_DIR  := coverage
-BINARY_NAME   := zodd
-BINARY_PATH   := $(BUILD_DIR)/bin/$(BINARY_NAME)
-TEST_EXECUTABLE := $(BUILD_DIR)/bin/test
-PREFIX        ?= /usr/local
 RELEASE_MODE := ReleaseSmall
 
 # Get all .zig files in the examples directory and extract their stem names
@@ -56,7 +51,7 @@ else
 	$(ZIG) build run-$(EXAMPLE) $(BUILD_OPTS)
 endif
 
-test: ## Run tests
+test: ## Run all tests (unit tests and tests in the `tests/` directory)
 	@echo "Running tests..."
 	$(ZIG) build test $(BUILD_OPTS) -j$(JOBS) --summary all
 
@@ -66,7 +61,7 @@ release: ## Build in Release mode
 
 clean: ## Remove docs, build artifacts, and cache directories
 	@echo "Removing build artifacts, cache, generated docs, and coverage files..."
-	rm -rf $(BUILD_DIR) $(CACHE_DIR) $(DOC_OUT) *.profraw $(COVERAGE_DIR)
+	rm -rf $(BUILD_DIR) $(CACHE_DIR) $(DOC_OUT) *.profraw
 
 lint: ## Check code style and formatting of Zig files
 	@echo "Running code style checks..."
@@ -77,20 +72,12 @@ format: ## Format Zig files
 	$(ZIG) fmt .
 
 docs: ## Generate API documentation
-	@echo "Generating documentation from $(DOC_SRC) to $(DOC_OUT)..."
+	@echo "Generating documentation..."
+	$(ZIG) build docs
+	@echo "Copying documentation to $(DOC_OUT)..."
+	rm -rf $(DOC_OUT)
 	mkdir -p $(DOC_OUT)
-	@if $(ZIG) doc --help > /dev/null 2>&1; then \
-	  $(ZIG) doc $(DOC_SRC) --output-dir $(DOC_OUT); \
-	else \
-	  $(ZIG) test -femit-docs $(DOC_SRC); \
-	  for f in docs/*; do \
-		base=$$(basename "$$f"); \
-		if [ "$$base" = "assets" ] || [ "$$base" = "api" ]; then \
-		  continue; \
-		fi; \
-		mv "$$f" $(DOC_OUT)/; \
-	  done; \
-	fi
+	cp -r $(BUILD_DIR)/docs/* $(DOC_OUT)
 
 docs-serve: ## Serve API documentation locally
 	@echo "Serving documentation at http://localhost:8000/..."

README.md

@@ -13,7 +13,7 @@
 [![Zig Version](https://img.shields.io/badge/Zig-0.15.2-orange?logo=zig&labelColor=282c34)](https://ziglang.org/download/)
 [![Release](https://img.shields.io/github/release/CogitatorTech/zodd.svg?label=release&style=flat&labelColor=282c34&logo=github)](https://github.com/CogitatorTech/zodd/releases/latest)
 
-A small embeddable Datalog engine in pure Zig
+A small embeddable Datalog engine in Zig
 
 </div>
 
@@ -27,7 +27,7 @@ Datalog is a declarative logic programming language that is used in deductive da
 It is a subset of [Prolog](https://en.wikipedia.org/wiki/Prolog) programming language and allows you to define things like facts and rules
 and then query those facts and rules to derive new information.
 
-Below is a simple Datalog code-snippet that defines a graph and computes the transitive closure (reachability) between nodes:
+Below is a simple Datalog code-snippet that defines a graph and computes the transitive closure of that graph:
 
 ```prolog
 % Facts: a graph (with four nodes and three edges)
@@ -36,8 +36,8 @@ edge(2, 3).
 edge(3, 4).
 
 % Rule: transitive closure of the graph
-% A transitive closure of a graph is a relation (a set of nodes) that contains all pairs of nodes
-% that are reachable from each other.
+% A transitive closure of a graph is a relation (a set of nodes) that contains all pairs
+% of nodes that are reachable from each other.
 reachable(X, Y) :- edge(X, Y).
 reachable(X, Z) :- reachable(X, Y), edge(Y, Z).
 ```
@@ -179,5 +179,6 @@ Zodd is licensed under the MIT License (see [LICENSE](LICENSE)).
 ### Acknowledgements
 
 * The logo is from [SVG Repo](https://www.svgrepo.com/svg/469003/gravity) with some modifications.
-* This project uses the [Minish](https://github.com/CogitatorTech/minish) framework for property-based testing.
-* Zodd is inspired and modeled after the [Datafrog](https://github.com/frankmcsherry/blog/blob/master/posts/2018-05-19.md) Datalog engine for Rust 🦀.
+* This project uses the [Minish](https://github.com/CogitatorTech/minish) framework for property-based testing and
+  the [Ordered](https://github.com/CogitatorTech/minish) Zig library.
+* Zodd is inspired and modeled after the [Datafrog](https://github.com/frankmcsherry/blog/blob/master/posts/2018-05-19.md) Datalog engine for Rust.

ROADMAP.md

@@ -8,34 +8,34 @@ This document outlines the features implemented in Zodd and the future goals for
 ### Core Features
 
 - [x] `Relation` - sorted, deduplicated tuple collections
-- [x] `Variable` - incremental update lifecycle (stable/recent/to_add)
+- [x] `Variable` - incremental update lifecycle
 - [x] `Iteration` - fixed-point computation context
 - [x] `gallop` - exponential and binary search for filtering
 - [x] `joinHelper` - merge-join on key-value tuples
 - [x] `joinInto` - high-level join between variables
-- [x] Treefrog Leapjoin interface (`Leaper`)
+- [x] `Leaper` - Treefrog Leapjoin interface
 - [x] `ExtendWith` - propose values from a relation
 - [x] `FilterAnti` - negation (filter out matching tuples)
 - [x] `ExtendAnti` - set difference (propose non-matching values)
 
-### Testing
+### Extra Features
 
-- [x] Unit tests in each module
-- [x] Integration, regression, and property-based tests in `tests` directory
-
-### Extensions
-
-- [ ] Stratified negation
-- [x] Aggregation
+- [x] Stratified negation
+- [x] Aggregations
 - [x] Recursion limits
-- [ ] Rule DSL
 - [x] Persistence
-- [ ] Secondary indices
-- [ ] Incremental maintenance
-- [ ] Query planner
+- [x] Secondary indices
+- [x] Incremental maintenance
 - [ ] Parallel execution
 - [ ] CLI interface
-- [ ] Magic sets
-- [ ] Benchmarks
 - [ ] WASM support
 - [ ] Streaming input
+- [ ] Rule DSL
+- [ ] Query planner
+- [ ] Magic sets
+
+### Development and Testing
+
+- [x] Unit tests in each module
+- [x] Integration, regression, property-based tests, etc. in `tests` directory
+- [ ] Benchmarks

build.zig

@@ -11,6 +11,13 @@ pub fn build(b: *std.Build) void {
         .optimize = optimize,
     });
 
+    // Add Ordered dependency to zodd module
+    const ordered_dep = b.dependency("ordered", .{
+        .target = target,
+        .optimize = optimize,
+    });
+    zodd_mod.addImport("ordered", ordered_dep.module("ordered"));
+
     // Static library artifact
     const lib = b.addLibrary(.{
         .name = "zodd",
@@ -32,7 +39,7 @@ pub fn build(b: *std.Build) void {
     // Discover and add tests from tests/ directory
     // (only available when developing zodd, not when used as a dependency)
     if (std.fs.cwd().openDir("tests", .{ .iterate = true })) |tests_dir| {
-        // Lazy-load minish dependency (only needed for property tests)
+        // Lazy-load Minish dependency (only needed for property tests)
         const minish_dep = b.dependency("minish", .{
             .target = target,
             .optimize = optimize,
@@ -104,13 +111,18 @@ pub fn build(b: *std.Build) void {
     } else |_| {}
 
     // API Documentation
-    const doc_step = b.step("docs", "Generate API documentation");
-    const doc_cmd = b.addSystemCommand(&[_][]const u8{
-        b.graph.zig_exe,
-        "build-lib",
-        "src/lib.zig",
-        "-femit-docs=docs/api",
-        "-fno-emit-bin",
+    const docs_step = b.step("docs", "Generate API documentation");
+
+    const doc_obj = b.addObject(.{
+        .name = "zodd",
+        .root_module = zodd_mod,
     });
-    doc_step.dependOn(&doc_cmd.step);
+
+    const install_docs = b.addInstallDirectory(.{
+        .source_dir = doc_obj.getEmittedDocs(),
+        .install_dir = .prefix,
+        .install_subdir = "docs",
+    });
+
+    docs_step.dependOn(&install_docs.step);
 }

docs/assets/.gitkeep

@@ -2,11 +2,11 @@
 
 #### List of Examples
 
-| # | File                                                   | Description                                                                                   |
-|---|--------------------------------------------------------|-----------------------------------------------------------------------------------------------|
-| 1 | [e1_transitive_closure.zig](e1_transitive_closure.zig) | Computes the transitive closure of a directed graph using Datalog rules.                      |
-| 2 | [e2_same_generation.zig](e2_same_generation.zig)       | Finds all pairs of nodes at the same depth in a hierarchy (siblings, cousins).                |
-| 3 | [e3_points_to_analysis.zig](e3_points_to_analysis.zig) | Performs points-to analysis for program analysis (alloc, assign, load, and store operations). |
+| # | File                                                   | Description                                                              |
+|---|--------------------------------------------------------|--------------------------------------------------------------------------|
+| 1 | [e1_transitive_closure.zig](e1_transitive_closure.zig) | Computes the transitive closure of a directed graph using Datalog rules. |
+| 2 | [e2_same_generation.zig](e2_same_generation.zig)       | Finds all pairs of nodes at the same depth in a hierarchy.               |
+| 3 | [e3_points_to_analysis.zig](e3_points_to_analysis.zig) | Performs points-to analysis for a program.                               |
 
 #### Running Examples
 

examples/README.md

@@ -1,9 +1,12 @@
+//! Zodd: A small embeddable Datalog engine for Zig.
+
 pub const relation = @import("zodd/relation.zig");
 pub const variable = @import("zodd/variable.zig");
 pub const iteration = @import("zodd/iteration.zig");
 pub const join = @import("zodd/join.zig");
 pub const extend = @import("zodd/extend.zig");
 
+pub const index = @import("zodd/indexing.zig");
 pub const aggregate = @import("zodd/aggregate.zig");
 
 pub const Relation = relation.Relation;
@@ -12,6 +15,7 @@ pub const gallop = variable.gallop;
 pub const Iteration = iteration.Iteration;
 pub const joinHelper = join.joinHelper;
 pub const joinInto = join.joinInto;
+pub const joinAnti = join.joinAnti;
 pub const Leaper = extend.Leaper;
 pub const ExtendWith = extend.ExtendWith;
 pub const FilterAnti = extend.FilterAnti;

src/lib.zig

@@ -1,3 +1,5 @@
+//! Group-by and aggregation primitives for relations.
+
 const std = @import("std");
 const Allocator = std.mem.Allocator;
 const Relation = @import("relation.zig").Relation;
@@ -18,13 +20,6 @@ pub fn aggregate(
         return Relation(ResultTuple).empty(allocator);
     }
 
-    // Since input is sorted by Tuple, but we might be grouping by arbitrary Key,
-    // the input might NOT be sorted by Key.
-    // If Key is a prefix of Tuple, it IS sorted by Key.
-    // Optimization: check if Key is prefix? For now, let's assume worst case and use a hash map or sort.
-    // Actually, sorting a persistent array is better than hash map for memory locality usually.
-
-    // Let's create an array of (Key, Val) and sort it by Key.
     const Intermediate = struct { Key, *const Tuple };
     var intermediates = try allocator.alloc(Intermediate, input.len());
     defer allocator.free(intermediates);
@@ -49,14 +44,12 @@ pub fn aggregate(
 
         for (intermediates) |item| {
             if (std.math.order(item[0], current_key) != .eq) {
-                // finish previous group
                 try results.append(allocator, .{ current_key, current_acc });
                 current_key = item[0];
                 current_acc = init_val;
             }
             current_acc = folder(current_acc, item[1]);
         }
-        // finish last group
         try results.append(allocator, .{ current_key, current_acc });
     }
 
@@ -65,7 +58,7 @@ pub fn aggregate(
 
 test "aggregate: sum by key" {
     const allocator = std.testing.allocator;
-    const Tuple = struct { u32, u32 }; // id, value
+    const Tuple = struct { u32, u32 };
 
     var data = try Relation(Tuple).fromSlice(allocator, &[_]Tuple{
         .{ 1, 10 },