NAME
Review::Helper::Journal - Notes an agent records while it works.
DESCRIPTION
The journal is a JSON Lines file, one note per line, kept per worktree as journal.jsonl in the VCS's state directory ("state_dir" in Review::Helper::VCS). A note with a flag is a flag to be; it waits there until it is placed into a review, which removes it. A note without one is a journal entry: the next build or iteration of a review takes it into that iteration's journal and removes it.
Every write holds an exclusive flock on the file, so concurrent agents in one worktree do not lose notes.
A note has id (UUID v7), created (epoch seconds), kind (deviation, assumption, self-review, test-revealed, note or other, the default), path, sentence, and the optional flag (the flag's color: yellow, a reviewer may object, or red, probably a problem), unit, snippet and detail, which are null when not given.
SYNOPSIS
use Review::Helper::Journal;
my $journal = Review::Helper::Journal->new(repo => $repo);
my $id = $journal->add(
flag => 'yellow',
kind => 'deviation',
path => 'lib/Foo.pm',
unit => 'bar',
sentence => 'Skips expiry when TTL is zero.',
);
my $notes = $journal->notes;
$journal->remove($id);
ATTRIBUTES
- $repo = $journal->repo()
-
The repository whose journal this is, a Review::Helper::VCS.
- $path = $journal->path()
-
The journal file. Defaults to the repository's journal location; pass it instead of
repoto use another file.
PUBLIC METHODS
- $id = $journal->add(%note)
-
Validate the note fields, append the note, and return its new id. Field values are character strings, not encoded bytes; the journal stores them as UTF-8. A missing
kindisother. Croaks on unknown fields, missing required fields, empty strings, aflagother thanyelloworred, or an unknown kind. Creates the file and its directory when needed. - $notes = $journal->notes()
-
Arrayref of every note in the journal, oldest first. Empty when there is no journal file. A line that is not a note is skipped with a warning naming it.
- $error = $journal->entry_error($note)
-
Why a note read from the journal is not one
addcould have written (a field missing, empty or invalid, anidthat is not a non-empty string, orcreatednot epoch seconds), or undef when it is. Fields other than the note's own are ignored. - $journal->remove(@ids)
-
Remove the notes with these ids. Ids not in the journal are ignored. A line that is not a note is kept as it is, with a warning.
SOURCE
The source code repository for Review-Helper can be found at https://github.com/exodist/Review-Helper.
MAINTAINERS
AUTHORS
COPYRIGHT
Copyright Chad Granum <exodist7@gmail.com>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.