File Coverage

=head1 NAME

App::FileSync::Scan - describe a directory tree as a manifest

=head1 SYNOPSIS

        my $scan = App::FileSync::Scan::scan(root => $root, ignore => $ignore, cache => $last);
        for my $path (sort keys %{ $scan->{manifest} }) { ... }
        printf "%d hashed, %d reused\n", @{ $scan->{stats} }{qw(hashed cached)};

=head1 FUNCTIONS

=head2 scan

Purpose: walk a tree and describe every regular file and empty directory.

Args: C<root> (required), C<ignore> (an L<App::FileSync::Ignore>), C<cache>
(a previous manifest whose entries are reused when size and mtime still match).

Returns: a hashref with three hashrefs:

        manifest  path => { t => 'f', s => size, m => mtime, h => sha256, mode => bits }
                  path => { t => 'd' }    (only directories empty after ignores)
        stats     { files, dirs, bytes, hashed, cached, skipped }
        skipped   path => reason, for symlinks, special files and unreadable entries

Side Effects: reads every file that is not cached.  Never writes.

Usage:

        my $scan = App::FileSync::Scan::scan(root => $master, ignore => $ignore);

=head3 EXAMPLE

        my $scan = App::FileSync::Scan::scan(root => '/home/foo/Documents');
        print scalar(keys %{ $scan->{manifest} }), " entries\n";

=head3 API SPECIFICATION

=head4 INPUT

        {
                root   => { type => 'string', min => 1 },
                ignore => { type => 'object', can => 'match', optional => 1 },
                cache  => { type => 'hashref', optional => 1 },
        }

=head4 OUTPUT

        {
                type => 'hashref',
                schema => {
                        manifest => { type => 'hashref' },
                        stats    => { type => 'hashref' },
                        skipped  => { type => 'hashref' },
                },
        }

=head3 MESSAGES

Skip reasons (in C<skipped>, not raised):

        Key                 Meaning
        scan.unreadable     a file could not be read
        scan.cannot_stat    an entry vanished or cannot be examined
        scan.cannot_list    a directory cannot be read
        scan.symlink        symbolic links are not synced
        scan.special        devices, sockets and fifos are not synced

        Key            Meaning               Resolution
        args.invalid   no root was given     pass root

=head3 FORMAL SPECIFICATION

        Manifest == PATH ⇸ ENTRY
        scan(r, ign, c) = (M, S, K) where
                dom M = { p | p ∈ files(r) ∪ emptydirs(r) ∧ ¬ ign(p) ∧ ¬ unreadable(p) }
                âˆ€ p ∈ dom M • kind p = file ⇒ M(p).h = sha256(FS(r/p))
                dom K ∩ dom M = ∅

=head3 PSEUDOCODE

        for each entry under root, depth first, sorted:
                skip ignored paths (and everything below an ignored directory)
                directory: recurse; record it only if nothing inside was recorded
                regular file: reuse the cached hash if size and mtime match, else hash it
                anything else: record why it was skipped

=cut

=head2 clean_stale_temps

Purpose: remove temporary files left behind by an interrupted run.

Args: C<root>, optional C<max_age> in seconds (default 3600).

Returns: the number of files removed.

Side Effects: deletes C<.filesync-tmp-*> files older than C<max_age> anywhere
under C<root>.  Younger ones may belong to a run in progress and are left
alone.  A file that cannot be removed is skipped.

Usage:

        App::FileSync::Scan::clean_stale_temps(root => $root);

=head3 EXAMPLE

        my $removed = App::FileSync::Scan::clean_stale_temps(root => '/srv/filesync/master/docs', max_age => 600);

=head3 API SPECIFICATION

=head4 INPUT

        {
                root    => { type => 'string', optional => 1 },
                max_age => { type => 'integer', min => 0, optional => 1 },
        }

=head4 OUTPUT

        { type => 'integer', min => 0 }

=head3 MESSAGES

None; failures to remove are not errors.

=head3 FORMAL SPECIFICATION

        Î”FS
        Stale == { p : dom FS | p under root ∧ prefix(TEMP, basename p) ∧ now − mtime p ≥ age }
        dom FS' = dom FS \ Removable(Stale)
        result = #(dom FS \ dom FS')

=cut