File Coverage

=head1 NAME

App::FileSync::Trash - dated trash with retention

=head1 SYNOPSIS

        my $where = App::FileSync::Trash::move_to_trash(
                src => $abs, rel => 'notes/a.txt', root => $trash_dir,
        );
        my $versions = App::FileSync::Trash::versions(root => $trash_dir, rel => 'notes/a.txt');
        App::FileSync::Trash::restore(src => $versions->[0], to => $abs);
        App::FileSync::Trash::prune(root => $trash_dir, days => 30);

=head1 FUNCTIONS

=head2 move_to_trash

Purpose: move a file or directory into today's trash bucket.

Args: C<src> (absolute path), C<rel> (its relative path, kept inside the
bucket), C<root> (the trash directory), optional C<epoch> (default now).

Returns: the absolute path it was moved to.  A second deletion of the same
path on the same day is kept as C<PATH.1>, then C<PATH.2>, and so on.

Side Effects: renames C<src>; across filesystems a file is copied (keeping its
mtime) and the original removed.

Usage:

        my $where = App::FileSync::Trash::move_to_trash(src => $abs, rel => $rel, root => $trash);

=head3 EXAMPLE

        App::FileSync::Trash::move_to_trash(
                src => '/home/foo/Documents/old.txt', rel => 'old.txt',
                root => '/home/foo/.filesync/trash/documents', epoch => time,
        );

=head3 API SPECIFICATION

=head4 INPUT

        {
                src   => { type => 'string', min => 1 },
                rel   => { type => 'string', min => 1 },
                root  => { type => 'string', min => 1 },
                epoch => { type => 'number', optional => 1 },
        }

=head4 OUTPUT

        { type => 'string', min => 1 }

=head3 MESSAGES

        Key           Meaning                                   Resolution
        trash.move    the entry could not be moved              check permissions
        io.mkdir      the bucket could not be created           check permissions

=head3 FORMAL SPECIFICATION

        Î”FS
        src?, rel?, root? : PATH ; t? : â„• ; dst! : PATH
        let b = root? / day(t?) / rel?
        dst! = b if b ∉ dom FS, else b ⁀ "." ⁀ min { n : ℕ₁ | b ⁀ "." ⁀ n ∉ dom FS }
        FS'(dst!) = FS(src?) ∧ src? ∉ dom FS'

=cut

=head2 prune

Purpose: remove day buckets older than the retention period.

Args: C<root>, optional C<days> (default 30; 0 or less disables pruning),
C<now> (default the current time), C<dry_run>.

Returns: an arrayref of the bucket directories removed (or that would be).

Side Effects: removes whole day directories.  A bucket that cannot be removed
is left and not reported.

Usage:

        my $removed = App::FileSync::Trash::prune(root => $trash, days => 30);

=head3 EXAMPLE

        my $would = App::FileSync::Trash::prune(root => $trash, days => 7, dry_run => 1);
        print "$_\n" for @{$would};

=head3 API SPECIFICATION

=head4 INPUT

        {
                root    => { type => 'string', optional => 1 },
                days    => { type => 'number', optional => 1 },
                now     => { type => 'number', optional => 1 },
                dry_run => { type => 'boolean', optional => 1 },
        }

=head4 OUTPUT

        { type => 'arrayref' }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        Î”FS
        Old == { b : buckets(root) | midnight(b) ≤ now − days × 86400 }
        dry_run ⇒ FS' = FS ∧ result = Old
        Â¬dry_run ⇒ result ⊆ Old ∧ ∀ b : result • b ∉ dom FS'

=cut

=head2 versions

Purpose: every stored version of a path.

Args: C<root>, C<rel>.

Returns: an arrayref of absolute paths, newest first: by day, then by the
same-day suffix (C<.2> before C<.1> before the unsuffixed first deletion).

Side Effects: none.

Usage:

        my $versions = App::FileSync::Trash::versions(root => $trash, rel => 'notes/a.txt');

=head3 EXAMPLE

        my ($newest) = @{ App::FileSync::Trash::versions(root => $trash, rel => 'a.txt') };

=head3 API SPECIFICATION

=head4 INPUT

        {
                root => { type => 'string', optional => 1 },
                rel  => { type => 'string', min => 1 },
        }

=head4 OUTPUT

        { type => 'arrayref' }

=head3 MESSAGES

        Key            Meaning              Resolution
        args.invalid   no rel was given     pass the path

=head3 FORMAL SPECIFICATION

        versions(root, rel) = sort_desc(day, suffix)
                { v | ∃ b : buckets(root) • v = b/rel ∨ ∃ n : ℕ₁ • v = b/rel ⁀ "." ⁀ n }

=cut

=head2 restore

Purpose: copy one trashed version out, keeping modes and mtimes.

Args: C<src> (a path from L</versions>), C<to> (the destination; must not exist).

Returns: C<to>.

Side Effects: copies a file, or a directory tree, to C<to>.  The trash entry is
left in place, so the same version can be restored twice.

Usage:

        App::FileSync::Trash::restore(src => $versions->[0], to => $abs);

=head3 EXAMPLE

        App::FileSync::Trash::restore(src => $version, to => '/tmp/recovered.txt');

=head3 API SPECIFICATION

=head4 INPUT

        {
                src => { type => 'string', min => 1 },
                to  => { type => 'string', min => 1 },
        }

=head4 OUTPUT

        { type => 'string', min => 1 }

=head3 MESSAGES

        Key                  Meaning                              Resolution
        trash.missing        the version is not there             list versions again
        trash.exists         the destination already exists       move it aside
        trash.cannot_stat    an entry cannot be examined          check permissions
        trash.not_regular    a special file is in the version     restore by hand
        io.copy              a file could not be copied           check space

=head3 FORMAL SPECIFICATION

        Î”FS
        pre src ∈ dom FS ∧ to ∉ dom FS
        post tree'(to) = tree(src) ∧ src ∈ dom FS'

=cut

=head2 date_of

Purpose: the trash day a stored path belongs to.

Args: C<$path>, as returned by L</versions> or L</move_to_trash>.

Returns: C<YYYY-MM-DD>, or C<undef> for a path outside a day bucket.  Both
C</> and C<\> separators are understood.

Side Effects: none.

Usage:

        my $date = App::FileSync::Trash::date_of($version);

=head3 EXAMPLE

        print App::FileSync::Trash::date_of('/t/trash/2026/10/22/a/b.txt'), "\n";     # 2026-10-22

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'path', type => 'string', optional => 1 } ]

=head4 OUTPUT

        { type => 'string', optional => 1, matches => qr/\A\d{4}-\d{2}-\d{2}\z/ }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        date_of(p ⁀ sep ⁀ yyyy ⁀ sep ⁀ mm ⁀ sep ⁀ dd ⁀ sep ⁀ q) = yyyy ⁀ "-" ⁀ mm ⁀ "-" ⁀ dd

=cut

=head2 version_info

Purpose: describe one trashed version for a listing.

Args: C<$path>, a path from L</versions>.

Returns: C<{ path, date, size, mtime }>; C<size> and C<mtime> are C<undef> if
the version has gone since it was listed.

Side Effects: stats the path.

Usage:

        my @rows = map { App::FileSync::Trash::version_info($_) } @{$versions};

=head3 EXAMPLE

        my $info = App::FileSync::Trash::version_info($versions->[0]);
        print "$info->{date} $info->{size} bytes\n";

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'path', type => 'string', min => 1 } ]

=head4 OUTPUT

        {
                type => 'hashref',
                schema => {
                        path  => { type => 'string' },
                        date  => { type => 'string', optional => 1 },
                        size  => { type => 'integer', optional => 1 },
                        mtime => { type => 'number', optional => 1 },
                },
        }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        version_info(p) = ⟨path ↦ p, date ↦ date_of(p), size ↦ size(FS(p)), mtime ↦ mtime(FS(p))⟩

=cut