File Coverage

=head1 NAME

App::FileSync::Verify - check a tree against its recorded manifest

=head1 SYNOPSIS

        my $report = App::FileSync::Verify::verify(
                root => $master, entries => $index, ignore => $ignore, sample => 50,
        );
        print $report->{ok} ? "clean\n" : "drift\n";

=head1 FUNCTIONS

=head2 verify

Purpose: report where a tree no longer matches its record.

Args: C<root> (required, a directory), C<entries> (the recorded manifest),
C<ignore> (an L<App::FileSync::Ignore>), C<deep> (rehash every file),
C<sample> (without C<deep>, rehash this many unchanged-looking files chosen at
random).

Without C<deep>, entries whose size and mtime still match are trusted, which
is what makes a verify of a large tree cheap.

Returns: a hashref:

        root, ok (1 when nothing differs), deep, files (regular files found),
        known (entries in the record), rehashed, trusted, sampled,
        modified => [ { p, expected, got } | { p, reason } | { p, expected, got, sampled } ],
        missing  => [ { p, t } ],
        extra    => [ { p, t } ]

Each list is sorted by path.

Side Effects: reads files; never writes.

Usage:

        my $report = App::FileSync::Verify::verify(root => $root, entries => $base, deep => 1);

=head3 EXAMPLE

        my $report = App::FileSync::Verify::verify(root => '/srv/filesync/master/docs', entries => $index);
        print "missing: $_->{p}\n" for @{ $report->{missing} };

=head3 API SPECIFICATION

=head4 INPUT

        {
                root    => { type => 'string', min => 1 },
                entries => { type => 'hashref', optional => 1 },
                ignore  => { type => 'object', optional => 1 },
                deep    => { type => 'boolean', optional => 1 },
                sample  => { type => 'integer', min => 0, optional => 1 },
        }

=head4 OUTPUT

        {
                type => 'hashref',
                schema => {
                        ok       => { type => 'integer', min => 0, max => 1 },
                        modified => { type => 'arrayref' },
                        missing  => { type => 'arrayref' },
                        extra    => { type => 'arrayref' },
                },
        }

=head3 MESSAGES

        Key                    Meaning                        Resolution
        verify.no_root         root is not a directory        check the path
        verify.type_changed    (a reason in "modified")       a file became a directory or back

=head3 FORMAL SPECIFICATION

        let M = scan(root).manifest ; E = entries
        missing  = { p ∈ dom E | p ∉ dom M ∧ ¬(E(p).t = d ∧ isdir(root/p)) }
        modified = { p ∈ dom E ∩ dom M | E(p).t ≠ M(p).t ∨ (E(p).t = f ∧ E(p).h ≠ M(p).h) }
        extra    = dom M \ dom E \ (missing ∪ modified)
        ok ⇔ missing = modified = extra = ∅

=head3 PSEUDOCODE

        scan the tree, reusing recorded hashes unless deep
        for each recorded path: missing, type changed, or hash differs
        every scanned path not recorded is extra
        if sampling: rehash that many trusted files and add any that differ
        sort the three lists and count

=cut