NAME
Review::Helper::Builder - Build a review file and add iterations to it.
DESCRIPTION
Turns a range of commits into review data. For each commit, oldest first, it records the commit's metadata and change id; for each file the commit changed, its status, kind, sizes and line counts. It splits no file: a text file starts with no sections (split_source none) until the agent filling the review names them through the fill sheet (Review::Helper::Sheet), which calls split_sections. Diffs and file contents are read from the repository (Review::Helper::VCS) and never stored.
Binary files are those the VCS reports as binary. Images and binary files are sized in bytes and have no sections; text files are sized in lines. Text is decoded as UTF-8, with malformed bytes replaced.
Commits on the mainline, the first-parent chain from the head, have no merge; every other commit records the merge that brought it in. A merge has no file changes of its own; the commits it brought in hold them.
A squashed review covers base..head as one combined entry instead of commit by commit: the head's revision, subject and message, the base as its parent (none when the base is the empty revision, i.e. the whole codebase), no change id, and the file changes between base and head. It is for reviewing or learning a codebase as it finally lands. The agent filling the review splits that entry into topics through the fill sheet: one entry per topic, each with the same revision and parent and only its topic's files.
Paths (the VCS's path specs) limit a review to matching files, so a large codebase can be split into several reviews. Without squashing, commits that change no matching file are left out, as are merges left with no commits.
Each iteration's head is pinned ("pin" in Review::Helper::VCS), under the name stored as its pin, once all database writes of the iteration have committed in one transaction.
A new iteration copies from the previous one:
for a commit with the same change id: its what, why and how, its reading order, its flags, and per file the what, object system and paradigms, and the file's sections (the agent's split, with their explanations) when the file reads the same on both sides of the commit. A flag's lines move with the diff between the two versions of its file; when the code under it changed, it is pending for the agent to decide on.
for a squashed iteration over the same base and paths: each file stays in the topic that held its path, and files in none go to an entry with no topic for the agent to place. A topic's entry pairs with the entry of the same topic (the one with no topic with the one with none) and takes its flags, and its reading order when it lists the same paths; its what, why and how too when, besides, every file reads the same; and each file's explanations and split when it reads the same.
Any other text file starts unsplit again, and the agent explains its new sections afresh: explanations are not carried by content.
SYNOPSIS
use Review::Helper::Builder;
my $builder = Review::Helper::Builder->new(repo => $repo);
my $file = $builder->build(base => 'main', title => 'Add caching');
my $db = Review::Helper::DB->open($file);
my $number = Review::Helper::Builder->new(repo => $repo, db => $db)->iterate();
ATTRIBUTES
- $repo = $builder->repo()
-
The repository holding the commits, a Review::Helper::VCS. Required.
- $db = $builder->db()
-
The Review::Helper::DB of the review. Required for
iterate;buildsets it. - $journal = $builder->journal()
-
The Review::Helper::Journal whose journal entries (notes without a
flag) each new iteration takes. Defaults to the repository's journal.
PUBLIC METHODS
- $file = $builder->build(base => $rev, %params)
- $file = $builder->build(squash => 1, %params)
-
Create a review of
base..headand its iteration 1, pin it, register it, and return the absolute path of the review file. Optionalhead(defaultHEAD),squash(a true value),paths(arrayref of path specs),title,source(a pull or merge request URL) andfile.baseis required unlesssquashis set; then it defaults to the empty revision.The default file is <name>.sqlite in the VCS's state directory ("state_dir" in Review::Helper::VCS), named after the head's branch or tag, or its short id, with a number added when taken. A
fileoutside the VCS's own directories must be inside the worktree. Croaks when the range has no commits, or nothing under the paths. On failure the new file is removed. - $number = $builder->iterate(%params)
-
Add the next iteration for
base..headand return its number.basedefaults to the previous iteration's base,headtoHEAD. The squash mode and paths are the previous iteration's. - $paths = $builder->check_paths($paths)
-
The path specs as a new arrayref, or undef for none. Croaks unless
$pathsis undef or an arrayref of non-empty strings. - $commits = $builder->collect_range(\%range)
-
collectorcollect_squashedfor a hashref ofbase,head,squashedandpaths. - $commits = $builder->collect($base_sha, $head_sha)
- $commits = $builder->collect($base_sha, $head_sha, \@paths)
-
The review data of every commit in the range, oldest first, as stored by
store, each withmerge_revisionnaming the merge that brought it in (undef on the mainline). With paths, only matching files, and only commits with some. Croaks when the range is empty. - $commits = $builder->collect_squashed($base_sha, $head_sha)
- $commits = $builder->collect_squashed($base_sha, $head_sha, \@paths)
-
The one combined entry of a squashed review. Croaks when nothing changed.
- $kept = $builder->drop_untouched(\@commits)
-
The commits that have file changes, and the merges that kept a commit.
- $owners = $builder->merge_owners(\%parents, \@revisions_oldest_first)
-
Hashref of each revision in the range off the mainline to the revision of the merge that brought it in.
%parentsmaps each revision of "revisions" in Review::Helper::VCS to its parents. A merge brings in the commits reachable from its second and later parents but not from its first; a nested merge's commits belong to it, not to the outer merge. No merge takes a mainline commit, so a branch that merged the mainline in does not take its commits. - $set = $builder->ancestors(\%parents, @revisions)
-
Hashref holding
@revisionsand their ancestors, limited to the commits in%parents(revision to parents). - $commit = $builder->collect_commit($revision)
- $commit = $builder->collect_commit($revision, $is_merge)
- $commit = $builder->collect_commit($revision, $is_merge, \@paths)
- $file = $builder->collect_file($commit_info, $change)
-
Review data of one commit, or of one of its changes from "range_changes" in Review::Helper::VCS. A merge gets no file changes.
- $file = $builder->submodule_file($change)
-
The review data of a submodule entry, which has no content here: kind
binary, sizes in bytes left unknown, no sections and zero line counts. - $texts = $builder->file_texts($revision, $parent, $change, $binary)
-
Hashref of
before_rawandafter_raw(bytes, missing when the side does not exist),beforeandafter(decoded, unless$binary), andhunks(the parsed diff). - $text = $builder->decode_text($bytes)
-
UTF-8 decode with malformed bytes replaced; undef stays undef.
- $size = $builder->size($texts, $side, $bytes)
-
Size of one side in bytes or lines; undef when the side does not exist.
- $sections = $builder->split_sections($texts, \@units)
-
Every section of an agent split of a text change, with its line counts.
@unitsare hashrefs withname,package,ranges,doc_rangesandold_ranges, sorted and sharing no line; one with norangesis a deleted section, holding onlyold_ranges. The live units cover every new-side line that is not blank; blank lines join them as Review::Helper::Split describes. A section with no changed line is kept, untouched (all its counts 0). - $builder->carry_forward($prev_iteration, \%range, $commits)
-
Copy explanations, reading order, flags (by
carry_from) and splits from the previous iteration (its row) into collected commits, matching commits by change id, in order when several share one, and a commit with no change id (an empty diff) by revision. Whensame_squashholds for the previous iteration and%range, the one collected squashed entry is first split bytopic_entries, and entries are matched by topic instead; an entry's reading order is copied only when both list the same paths, and itswhat/why/howonly when, besides, every file reads the same in both. The first entry also lists, incarry_also, the previous entries no entry pairs with (a topic left with no file), so their flags are carried to it. - $entries = $builder->topic_entries(\@prev_entries, $entry)
-
A collected squashed entry split by the topics of the previous iteration's entries (stored rows): one entry per topic, in their order, holding the files whose path was in it, then one with no
topicfor the files in none. Topics left with no file are dropped.[$entry]when no previous entry has a topic. - $bool = $builder->same_squash($old, $new)
-
True when both iterations (stored rows, or a range with
pathsas an arrayref) are squashed with the samebaseandpaths. - $builder->carry_file($file, $old_file, $old_commit, $commit, $squash, $order)
-
Copy one file's reading position (unless
$orderis false) and explanations from the same file in$old_commit, and its split (sections andsplit_source) when it has one and the file reads the same in both commits, before and after them. Commits are hashrefs withrevisionandparent. With$squash, the explanations too are copied only when the file reads the same after both.$squashand$orderare optional, defaulting to false and true. The contents are compared only when the answer is needed. Returns whether the file reads the same after both commits; false when that was not compared. - $files = $builder->stored_files($commit_id)
-
A stored commit's file rows, each with its decoded
sections. - $builder->store($number, \%range, $commits)
-
Write an iteration (
base,head,squashedandpathsfrom%range) and its commits in one transaction, closing orphaned split requests and making flags off the change pending from iteration 2 on, and taking the journal's entries (store_journal), then pin its head and remove those entries from the journal once the transaction has committed. A failed removal only warns: the iteration stands, and the next build or iteration ignores the entries it already holds. - @entries = $builder->journal_entries()
-
The journal's notes without a
flag, skipping with a warning any noteentry_errorin Review::Helper::Journal finds fault with. - $builder->store_journal($number, $entries)
-
Store journal notes without a
flagas iteration$number's journal entries. One the file already holds keeps its iteration. - $builder->close_orphaned_requests($number)
-
Close each open
splitrequest whose commit is not in iteration$number: its status becomesdoneand(closed: its commit was rewritten)is appended to its note. - $builder->flags_off_change($number)
-
Make pending, without seen marks, each flag of iteration
$numberwhose file left the change in that iteration: no entry with its commit's revision changes its path, while in the previous iteration an entry with that flag's commit's revision changed the path the flag had there (a squashed change reverted to the base, say). The agent decides on it even when its lines read the same. A flag kept on a file already outside the change carries settled, with its marks. - $builder->carry_unpaired_flags($number, \@commits)
-
In an iteration that is not squashed, copy the flags of each previous commit no commit in
\@commitscarries from (rewritten, so its change id changed, or dropped), pending and without seen marks: onto the last commit of iteration$numberthat changes the flag's path, its lines moved by the diff between the two commits' files where it keeps any, else on the whole file; with no commit changing the path, or no path, onto the iteration's last commit, flagging the whole file. - $id = $builder->store_commit($number, $position, $commit)
- $builder->store_file($commit_id, $file)
- $builder->store_sections($file_id, $sections)
-
Insert one commit (with carried flags; returns its id), file, or file's sections.
- $builder->carry_flags($commit_id, $commit)
- $builder->carry_flags($commit_id, $commit, $from)
-
Copy the flags of the stored commit
$from(default$commit->{carry_from}) to the new commit$commit_id, with their color.store_commitcalls it forcarry_fromand for each id incarry_also. A flag on a file the VCS finds renamed between the two commits takes the file's new path. A flag whose code is unchanged (a line flag whose lines the diff between the two versions of its file only moves, a whole-file flag whose file reads the same, or a flag with no path) keeps its moved lines and every reviewer'sflag_seenmark, with its time. Any other ispending, with no seen marks, on the span from the first to the last of its lines the diff kept, or on the whole file when it kept none or the file exists in only one of the commits.flags_off_changethen makes pending a flag whose file left the change in the new iteration. - ($start, $end) = $builder->kept_span($hunks, $start, $end)
-
The first and last new line numbers of the lines
$startto$endthat$hunkskeep; empty when they keep none. - $path = $builder->renamed_to(\%old_commit, \%new_commit, $path)
-
The path
$pathin the old commit has in the new one when the VCS finds the file renamed between them; undef when the new commit still has$path, the old one does not, or no rename is found. - $builder->flags_to_paths($number)
-
In squashed iteration
$number, move each flag with a path to the entry holding that path. - $hunks = $builder->line_moves(\%old_commit, \%new_commit, $path)
- $hunks = $builder->line_moves(\%old_commit, \%new_commit, $path, $to_path)
-
The parsed diff hunks from
$pathin one commit to$to_path(default$path; the file's new path when it was renamed) in the other (each a hashref withrevisionandparent): empty when the file reads the same, undef when it exists in only one. A file deleted in both is compared before them. - $file = $builder->default_file($rev, $revision)
- $name = $builder->default_name($rev, $revision)
-
The default review file for a head, and the name it is based on.
- $path = $builder->resolve_file($file)
-
Absolute path, with symlinks in an existing directory resolved.
- $builder->check_location($file)
-
Croak when
$fileis outside both the VCS's own directories and the worktree.
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.