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 repo to 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 kind is other. Croaks on unknown fields, missing required fields, empty strings, a flag other than yellow or red, 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 add could have written (a field missing, empty or invalid, an id that is not a non-empty string, or created not 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

Chad Granum <exodist7@gmail.com>

AUTHORS

Chad Granum <exodist7@gmail.com>

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.

See https://dev.perl.org/licenses/