//! The in-memory rule draft (M1-UI-008, M1-UI-015, M1-UI-016, M1-UI-019). //! //! The editor holds rules as structured fields, never as text. M1-UI-008 //! forbids exposing the rules file as a raw YAML editor, and the way to be //! sure of that is for no path into this module to accept YAML: `decode` //! takes a JSON array of name, condition and accounts, and anything else is //! refused. //! //! Dirtiness (M1-UI-015) is decided by comparing canonical renderings rather //! than the bytes on disk. That is what makes M1-AC-010 come out right: a //! saved file whose rules are merely in a different order, or carry comments, //! is the same ruleset, and the editor should not claim otherwise. //! //! A draft may hold no rules at all (M1-UI-019). Such a draft has no canonical //! rendering -- a rules file always has at least one rule -- which is exactly //! what makes saving unavailable, with no separate flag to keep in step. const std = @import("std"); const diag = @import("../diag.zig"); const emit = @import("../yaml/emit.zig"); const config_rules = @import("../config/rules.zig"); pub const Error = error{OutOfMemory}; /// The editable shape of a rule. Same type the canonical writer takes, so /// what the interface holds is exactly what a save writes. pub const Rule = emit.Rule; const Editor = @This(); /// The draft, in the order the interface shows it. rules: []const emit.Rule, /// Canonical text of the last known saved ruleset. Null when the rules /// file could not be loaded, in which case nothing is known to be saved. saved: ?[]const u8, /// Starts from what was loaded from disk. pub fn fromSaved(arena: std.mem.Allocator, ruleset: config_rules.Ruleset) Error!Editor { const drafted = try arena.alloc(emit.Rule, ruleset.rules.len); for (ruleset.rules, 0..) |rule, index| { drafted[index] = .{ .name = rule.name, .match = rule.match, // A rule that loaded without a usable action (M1-RULE-013) // still has to appear, so it can be repaired. .target_account = if (rule.action) |action| action.target_account else "", .source_account = if (rule.action) |action| action.source_account else null, }; } var editor: Editor = .{ .rules = drafted, .saved = null }; editor.saved = try editor.canonical(arena); return editor; } pub fn replace(self: *Editor, drafted: []const emit.Rule) void { self.rules = drafted; } /// Records that `text` is now on disk. The caller passes the same bytes it /// wrote, so the baseline cannot drift from the file. pub fn markSaved(self: *Editor, text: []const u8) void { self.saved = text; } /// The bytes a save would write, or null when the draft holds no rules and /// so cannot be written at all (M1-UI-019). pub fn canonical(self: Editor, arena: std.mem.Allocator) Error!?[]const u8 { return emit.rulesFile(arena, self.rules) catch |err| switch (err) { error.NoRules => null, error.OutOfMemory => error.OutOfMemory, }; } /// M1-UI-015. An unknown baseline counts as different: the safe answer is /// to tell the user their work is unsaved. pub fn dirty(self: Editor, arena: std.mem.Allocator) Error!bool { const base = self.saved orelse return true; const now = try self.canonical(arena) orelse return true; return !std.mem.eql(u8, base, now); } /// The wire shape of one rule. The field names are the YAML keys, so the /// interface, the JSON and the saved file all call the same thing by the same /// name. Both directions use it: `decode` parses one from a PUT body, and /// `state` renders one into the state payload (M1-UI-008 requires the /// interface round-trip what it was given, so the two must not drift). /// /// `sourceAccount` defaults so a body may leave it out; rendering always sets /// every field. pub const Wire = struct { match: []const u8, name: []const u8, sourceAccount: ?[]const u8 = null, // zlinter-disable-current-line field_naming targetAccount: []const u8, // zlinter-disable-current-line field_naming }; const Body = struct { rules: []const Wire, }; /// Decodes an edit. Returns null, with a diagnostic, for anything that is not /// a draft -- including a body of YAML, which is the shape M1-UI-008 rules /// out. pub fn decode( arena: std.mem.Allocator, body: []const u8, diags: *diag.List, ) Error!?[]const emit.Rule { const parsed = std.json.parseFromSliceLeaky(Body, arena, body, .{}) catch { try diags.add(.{ .message = "the edit was not a list of rules" }); return null; }; const drafted = try arena.alloc(emit.Rule, parsed.rules.len); for (parsed.rules, 0..) |rule, index| { // M1-UI-016: names are non-empty and unique. Both are checked here // rather than left to the round trip, because "a rule needs a name" // is a better thing to read than a YAML key error. if (rule.name.len == 0) { try diags.add(.{ .message = "every rule needs a name" }); return null; } inner: for (parsed.rules[0..index]) |earlier| { if (!std.mem.eql(u8, earlier.name, rule.name)) continue :inner; try diags.addFmt("'{s}' is used by more than one rule", .{rule.name}, .{}); return null; } drafted[index] = .{ .name = rule.name, .match = rule.match, .target_account = rule.targetAccount, .source_account = rule.sourceAccount, }; } return drafted; } // -- tests ------------------------------------------------------------------- const expect = std.testing.expect; const expectEqual = std.testing.expectEqual; const expectEqualStrings = std.testing.expectEqualStrings; const saved_rules = @embedFile("../testdata/ui/saved_rules.yaml"); fn loadSaved(arena: std.mem.Allocator, text: []const u8) !Editor { const diags = try diag.List.create(arena); const ruleset = try config_rules.load(arena, "rules.yaml", text, diags); return Editor.fromSaved(arena, ruleset); } test "M1-UI-015: a freshly loaded editor is not dirty" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var editor = try loadSaved(alloc, saved_rules); try expect(!try editor.dirty(alloc)); } test "M1-AC-010: reordering the file alone does not make the editor dirty" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); // The saved file lists b before a. The baseline is canonical, so the // draft -- which is also canonical -- matches it despite the file order. var editor = try loadSaved(alloc, saved_rules); try expectEqualStrings("b", editor.rules[0].name); try expect(!try editor.dirty(alloc)); } test "M1-UI-015: an edit makes the editor dirty, and undoing it does not stay dirty" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var editor = try loadSaved(alloc, saved_rules); const before = editor.rules; const edited = try alloc.dupe(emit.Rule, before); edited[0].target_account = "e:changed"; editor.replace(edited); try expect(try editor.dirty(alloc)); editor.replace(before); try expect(!try editor.dirty(alloc)); } test "M1-UI-019: an editor holding zero rules is dirty and has nothing to save" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var editor = try loadSaved(alloc, saved_rules); editor.replace(&.{}); try expect(try editor.dirty(alloc)); try expectEqual(@as(?[]const u8, null), try editor.canonical(alloc)); } test "M1-PROJ-018: with no loadable baseline the editor starts dirty" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); // The rules file did not load, so there is no known saved state and the // draft cannot be assumed to match it. var editor: Editor = .{ .rules = &.{}, .saved = null }; try expect(try editor.dirty(alloc)); editor.replace(&.{.{ .name = "r", .match = "a == \"1\"", .target_account = "e:f", .source_account = null, }}); try expect(try editor.dirty(alloc)); } test "M1-UI-015: a successful save clears the dirty state" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var editor = try loadSaved(alloc, saved_rules); const edited = try alloc.dupe(emit.Rule, editor.rules); edited[0].target_account = "e:changed"; editor.replace(edited); const text = (try editor.canonical(alloc)).?; editor.markSaved(text); try expect(!try editor.dirty(alloc)); } test "M1-UI-008: a draft arrives as structured fields, never as YAML text" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc); const body = @embedFile("../testdata/ui/a_draft_arrives_as_structured_fields_never_as_yaml_text.json"); const decoded = (try decode(alloc, body, diags)).?; try expectEqual(@as(usize, 2), decoded.len); try expectEqualStrings("one", decoded[0].name); try expectEqualStrings("a == \"1\"", decoded[0].match); try expectEqualStrings("e:f", decoded[0].target_account); try expectEqual(@as(?[]const u8, null), decoded[0].source_account); try expectEqualStrings("assets:x", decoded[1].source_account.?); } test "M1-UI-008: a body of raw YAML is refused" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc); // There is no endpoint anywhere that takes the rules file as text; this // is what happens when something tries. try expectEqual(@as(?[]const emit.Rule, null), try decode(alloc, saved_rules, diags)); try expect(diags.items.items.len > 0); } test "M1-UI-019: an empty draft decodes, because the editor may hold none" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc); const decoded = (try decode(alloc, "{\"rules\":[]}", diags)).?; try expectEqual(@as(usize, 0), decoded.len); } test "M1-UI-016: a rule with an empty name is refused before anything is written" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc); const body = "{\"rules\":[{\"name\":\"\",\"match\":\"a == \\\"1\\\"\",\"targetAccount\":\"e:f\"}]}"; try expectEqual(@as(?[]const emit.Rule, null), try decode(alloc, body, diags)); try expect(std.mem.find(u8, diags.items.items[0].message, "name") != null); } test "M1-UI-016: duplicate names are refused" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc); const body = @embedFile("../testdata/ui/duplicate_names_are_refused.json"); try expectEqual(@as(?[]const emit.Rule, null), try decode(alloc, body, diags)); try expect(std.mem.find(u8, diags.items.items[0].message, "r") != null); } test "M1-UI-016: an unknown field is refused rather than ignored" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc); const body = "{\"rules\":[{\"name\":\"r\",\"match\":\"a\",\"targetAccount\":\"e:f\",\"x\":1}]}"; try expectEqual(@as(?[]const emit.Rule, null), try decode(alloc, body, diags)); } test "M1-UI-016: a draft renders to exactly the bytes a save would write" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var editor = try loadSaved(alloc, saved_rules); const text = (try editor.canonical(alloc)).?; // What is validated is what is written: the canonical text is produced // once and both checked and saved. const diags = try diag.List.create(alloc); const reloaded = try config_rules.load(alloc, "rules.yaml", text, diags); try expectEqual(@as(usize, 2), reloaded.rules.len); }