NAME

Review::Helper::Sheet - Export the fill sheet and import a filled one.

DESCRIPTION

The fill sheet is the only way an agent writes review text. sheet lists every item of the latest iteration that still needs agent input; fill validates a filled sheet as a whole and writes it in one transaction.

Item types: summary (from iteration 2 it also takes note, what the iteration changed), topics (a squashed iteration's files grouped into named topics, each an entry of its own), commit, order (reading order), file, section, split, note (placing a journal note as a flag), flag (keeping, re-rating or retiring a flag), feedback, debate and guide. Each item has an id, a type, a rev, read-only about context, and fields holding the current values. The rev is a SHA-256 hex digest of the item's about and current field values, so an item filled from an out-of-date sheet is rejected.

An item is done once its required fields are set: what for files and sections, sections for splits, commit for notes (a null path places the note on the whole commit, null lines on the whole file), decision for a pending flag (any other flag is done), and every field for the other types. Done items are left out of the sheet unless it is asked for all; then they are listed with their current values and revs, and fill replaces what is given, checked as fully as a first fill. Flags that are not pending and finished debates are done items; note items never are, since a placed note leaves the journal. A done split item keeps null fields; its about shows the current units. Feedback is listed only while open, since its status may be the reviewer's. Every text file its commit adds, or changes a line of without deleting it, has a split item (a rename or mode change alone has none): required (optional in a squashed iteration) until the file is split, and required again while a split request on it is open. Its about gives the file's old path and status, its sizes, its stored units (the whole split), and, for a file not split yet, the newest split an earlier iteration stored for it, as stored, with that commit's revision. Section items are given only for touched sections: deleted, or with a line added, removed or changed. Deleted, image and binary files have no lines to split and get no split item, even when requested. Note items are always optional, since the journal can hold notes from unrelated work, and so are section and reading order items of a squashed iteration. A flag item is required for each pending flag: one the builder carried onto code that changed; with all every flag of the iteration has one. Feedback and debate items cover everything still open, from any iteration, and with all every debate. A commit with no file changes, such as a merge, has no reading order item. A commit item's about names the merge that brought the commit in, if any.

fill skips items whose fields are all null and writes only non-null fields. It rejects the whole sheet, naming every failing item, on: unknown ids or fields, wrong types, stale revisions, empty strings, ranges outside the file, a split section that overlaps another, repeats a name in its package, or whose first_line (old_first_line) is not the text of its first line, a split that leaves a line with text in no section (it covers every line or is empty), a reading order that is not exactly the commit's paths, guide targets or highlights missing from the iteration (a view step may show any file as of any commit of the iteration, new side only), and guide commentary over 400 characters or containing code tokens (backticks, ->, ::, (), or $, @ or % before a word character).

The topics item of a squashed iteration is required while a file is in no topic, which before its first fill means every file, in the iteration's one entry. Filled, every path in exactly one topic and the names unique, it makes the entries the topics, in order: a topic keeps the entry of its name, else one with exactly its files, else gets a new one; a kept entry whose files change loses its text and reading order; flags follow their paths; commit feedback and requests on an entry that goes move to the review, keeping the commit and topic as context. Commit, order, note and guide items are refused in the sheet that fills the topics. Every topic's entry has the head's revision, so a note or guide target picks its entry by topic, or by the path it names; a commit or diff step with no path, and a note with none, must name the topic.

Writing a split replaces the file's sections: the agent's units, with the blank lines it left out joined to them, and its deleted units; an empty split leaves the file with none. Line counts are computed from the diff, and every section is kept, touched or not, with no explanation: a re-split file is explained afresh. Section feedback and section requests whose section is gone, or no longer touched, move to the file, keeping its name as context. The file is labeled agent, and an open split request on it is marked done. Placed notes become flags and leave the journal once the transaction commits; a note the iteration already holds as a flag (its removal failed) gets no item and leaves at the next fill. A filled flag item settles a pending flag: keep leaves it as it is, recolor stores a new color and its reason (yellow turned red makes the flag unseen by everyone again); retire deletes it from the iteration, turning its feedback into file feedback (commit for a whole-commit flag) that keeps the flag's note id. A stored guide step naming a retired flag makes the guide due again. Addressed feedback records the latest iteration as resolved_in; a debate is done once both cases are set. A guide replaces the iteration's steps, storing each target's commit as its full revision id.

SYNOPSIS

use Review::Helper::Sheet;

my $sheet = Review::Helper::Sheet->new(repo => $repo, db => $db);

my $data = $sheet->sheet;
$_->{fields}->{what} = '...' for grep { $_->{type} eq 'section' } @{$data->{items}};

my $result = $sheet->fill($data);    # { filled => 3, remaining => 7 }

ATTRIBUTES

$repo = $sheet->repo()

The repository the review belongs to, a Review::Helper::VCS. Required.

$db = $sheet->db()

The Review::Helper::DB of the review. Required.

$journal = $sheet->journal()

The Review::Helper::Journal holding notes to place. Defaults to the repository's journal.

PUBLIC METHODS

$data = $sheet->sheet()
$data = $sheet->sheet(all => 1)

The fill sheet for the latest iteration: a hashref with format (review-sheet), format_version (1), review, iteration and items. With all, done items are listed too.

$result = $sheet->fill($data)

Validate and import a decoded sheet. Returns { filled => $n, remaining => $m }: the items written, and the required items still not done. Dies with one line per problem when the sheet is rejected, writing nothing.

$ctx = $sheet->context()

The latest iteration loaded for building items: review, iteration, commits with their files and sections, open feedback, every request, guide steps, the journal's flag notes (journal entries go in at the next build or iteration), the iteration's flags by note id, and its flag rows (with their entry's revision and topic).

$hex = $sheet->rev($item)

The item's revision hash.

$items = $sheet->items($ctx)

Every item of the iteration, done or not, with internal keys (done, optional, row, and names for text items) beside the exported ones.

$item = $sheet->summary_item($ctx)
$item = $sheet->topics_item($ctx)
$item = $sheet->text_item($ctx, $type, $id, $row, $about)
$item = $sheet->order_item($commit)
$about = $sheet->commit_about($ctx, $commit)
$about = $sheet->file_about($commit, $file)
$about = $sheet->section_about($commit, $file, $section)
@items = $sheet->split_item($ctx, $commit, $file)
$entry = $sheet->split_entry($section)
$texts = $sheet->file_texts($ctx, $commit, $file)
$previous = $sheet->previous_split($ctx, $commit, $file)
$bool = $sheet->is_split_request($request, $commit, $file)
$item = $sheet->note_item($note)
$item = $sheet->flag_item($ctx, $flag)
$item = $sheet->feedback_item($ctx, $feedback)
$item = $sheet->debate_item($request)
$item = $sheet->guide_item($ctx)
$bool = $sheet->is_stale_step($ctx, $target)

Build one item, or part of one. Only the sections the commit changed ("section_touched" in Review::Helper::DB) get section items. is_stale_step is true for a stored guide step naming a section that a later re-split removed or left untouched, a flag the iteration no longer has (a retired one), or a commit, topic or path that a later topics fill took away (a commit with no topic, once the iteration is split into topics); the guide item is then not done, so the sheet asks for the guide again.

$bool = $sheet->is_text($value)
@errors = $sheet->check_summary($ctx, $item, $fields, $plan)
@errors = $sheet->check_commit($ctx, $item, $fields, $plan)
@errors = $sheet->check_file($ctx, $item, $fields, $plan)
@errors = $sheet->check_debate($ctx, $item, $fields, $plan)
@errors = $sheet->check_flag($ctx, $item, $fields, $plan)
$file = $sheet->find_file($commit, $path)
$value = $sheet->trim($value)
$bool = $sheet->is_line($value)
$ranges = $sheet->sorted($ranges)

Small validation helpers: is_text and is_line test one value, trim drops whitespace at both ends of a string (section, package and topic names are trimmed before they are checked), the check_* methods check an item's fields (check_flag also records a retired flag in $plan, so a guide step in the same sheet cannot name it), find_file finds a changed file of a commit, and sorted orders ranges.

($plan, $errors) = $sheet->validate($ctx, $data)

Check a whole sheet. $errors lists every problem; $plan holds the writes and the splits and note placements they need.

($item, $fields, @errors) = $sheet->check_item($entry, $items, $index)

Match one sheet entry to its item and check its id, type, rev and field names. Returns nothing for a skipped entry.

$bool = $sheet->same_topics($given, $stored)

Whether given topics are the stored ones: the same names in the same order, each with the same paths in any order. A topics entry that repeats the stored topics is skipped.

@errors = $sheet->check_text($item, $fields, @names)
@errors = $sheet->check_section($ctx, $item, $fields, $plan)
@errors = $sheet->check_order($ctx, $item, $fields, $plan)
@errors = $sheet->check_feedback($ctx, $item, $fields, $plan)
@errors = $sheet->check_note($ctx, $item, $fields, $plan)
@errors = $sheet->check_topics($ctx, $item, $fields, $plan)

Check one item's fields. check_topics also records the topics in $plan, so the items a topics fill would move are refused.

($commit, $error) = $sheet->find_commit($ctx, $revision)
($commit, $error) = $sheet->find_commit($ctx, $revision, $topic, $path)

A commit entry of the iteration by its full revision id, matched exactly. In a squashed iteration split into topics, where every topic's entry has the head's revision, $topic picks one; else the entry holding $path, else the first; with neither, it is an error.

$error = $sheet->check_range($lines)
$error = $sheet->check_lines($file, $side, $lines)
@errors = $sheet->check_split($ctx, $item, $fields, $plan)
@errors = $sheet->check_coverage(\@lines, \@claimed)
@errors = $sheet->check_unit($file, \%lines, $unit, \%claimed, $n)
@errors = $sheet->check_ranges($file, $side, $ranges, \%claimed, $n)
@errors = $sheet->check_first_line($unit, $key, $ranges, $lines)
@errors = $sheet->check_name($unit, \%names)
@errors = $sheet->check_guide($ctx, $item, $fields, $plan)
@errors = $sheet->check_step($ctx, $plan, $step)
@errors = $sheet->check_commentary($text)
($commit, @errors) = $sheet->check_target($ctx, $plan, $target)
@errors = $sheet->check_view($ctx, $commit, $side, $path, $lines)
($commit, @errors) = $sheet->check_flag_target($ctx, $plan, $target)
@errors = $sheet->check_section_target($plan, $file, $section)
@errors = $sheet->check_highlight($ctx, $commit, $mark, $is_view)

Validation steps. Each returns error messages; an empty list means valid.

$sections = $sheet->resplit($ctx, $commit, $file, $texts, \@entries)

A split item's file sections from its entries: the agent's units and the blank lines between them, line counts from the diff, and no explanations.

$sheet->write_summary($ctx, $item, $fields, $plan)
$sheet->write_commit($ctx, $item, $fields, $plan)
$sheet->write_file($ctx, $item, $fields, $plan)
$sheet->write_section($ctx, $item, $fields, $plan)
$sheet->write_flag($ctx, $item, $fields, $plan)
$sheet->write_order($ctx, $item, $fields, $plan)
$sheet->write_split($ctx, $item, $fields, $plan)
$sheet->write_note($ctx, $item, $fields, $plan)
$sheet->write_feedback($ctx, $item, $fields, $plan)
$sheet->write_debate($ctx, $item, $fields, $plan)
$sheet->write_guide($ctx, $item, $fields, $plan)
$sheet->write_topics($ctx, $item, $fields, $plan)

Write one validated item. Called inside the fill transaction.

$id = $sheet->keep_entry($ctx, $entry, $name, $position, $same_files)
$id = $sheet->new_entry($from_entry, $name, $position)

Called by write_topics: keep an entry for a topic (renamed, its commit feedback and requests taking the new name; its text and reading order cleared unless $same_files), or make a new one with $from_entry's commit facts and no text.

$sheet->move_feedback($commit, $file, \@sections)

Called by write_split before an agent split replaces the file's sections. Section feedback and section requests on the file stay on the new section with its name and package. Those whose section is gone, or is no longer touched (the page shows only touched sections), move to the file, keeping the section's name and package as context: where they were given. Nothing else about them changes.

$sheet->update($table, \%where, \%set)

Run one UPDATE.

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/