# documentation -- lintian check script -*- perl -*-

# Copyright © 1998 Christian Schwarz and Richard Braakman
# Copyright © 2020 Felix Lechner
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, you can find it on the World Wide
# Web at http://www.gnu.org/copyleft/gpl.html, or write to the Free
# Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
# MA 02110-1301, USA.

package Lintian::documentation;

use v5.20;
use warnings;
use utf8;
use autodie;

use List::MoreUtils qw(any);

use Lintian::Util qw(open_gz);

use Moo;
use namespace::clean;

with 'Lintian::Check';

# a list of regex for detecting documentation file checked against basename (xi)
my @DOCUMENTATION_FILE_REGEXES = qw{
  \.docx?$
  \.html?$
  \.info$
  \.latex$
  \.markdown$
  \.md$
  \.odt$
  \.pdf$
  \.readme$
  \.rmd$
  \.rst$
  \.rtf$
  \.tex$
  \.txt$
  ^code[-_]of[-_]conduct$
  ^contribut(?:e|ing)$
  ^copyright$
  ^licen[sc]es?$
  ^howto$
  ^patents?$
  ^readme(?:\.?first|\.1st|\.debian|\.source)?$
  ^todos?$
};

my $COMPRESS_FILE_EXTENSIONS
  = Lintian::Data->new('files/compressed-file-extensions',
    qr/\s++/,sub { return qr/\Q$_[0]\E/ });

# an OR (|) regex of all compressed extension
my $COMPRESS_FILE_EXTENSIONS_OR_ALL = sub { qr/(:?$_[0])/ }
  ->(
    join('|',
        map {$COMPRESS_FILE_EXTENSIONS->value($_) }
          $COMPRESS_FILE_EXTENSIONS->all));

has ppkg => (is => 'rwp');

sub setup_installed_files {
    my ($self) = @_;

    $self->_set_ppkg(quotemeta($self->processable->name));

    return;
}

sub visit_installed_files {
    my ($self, $file) = @_;

    my $ppkg = $self->ppkg;

    if ($self->processable->type eq 'udeb') {
        if ($file->name =~ m,^usr/share/(?:doc|info)/\S,) {

            $self->hint('udeb-contains-documentation-file', $file->name);
            return;
        }
    }

    if ($file->name =~ m,^usr/share/info/dir(?:\.old)?(?:\.gz)?$,) {
        $self->hint('package-contains-info-dir-file', $file->name);
    }

    # doxygen md5sum
    if ($file->name =~ m{^usr/share/doc/$ppkg/[^/]+/.+\.md5$}s) {

        $self->hint('useless-autogenerated-doxygen-file', $file->name)
          if $file->parent_dir->child('doxygen.png');
    }

    # doxygen compressed map
    if (
        $file->name =~ m{^usr/share/doc/(?:.+/)?(?:doxygen|html)/
                         .*\.map\.$COMPRESS_FILE_EXTENSIONS_OR_ALL}xs
    ) {
        $self->hint('compressed-documentation', $file->name);
    }

    if ($file->is_file) {

        unless (
               $file->name =~ m{^etc/}
            || $file->name =~ m{^usr/share/(?:doc|help)/}
            # No need for dh-r packages to automatically
            # create overrides if we just allow them all to
            # begin with.
            || $file->dirname =~ 'usr/lib/R/site-library/'
            # SNMP MIB files, see Bug#971427
            || $file->dirname eq 'usr/share/snmp/mibs/'
            # see Bug#904852
            || $file->dirname =~ m{templates?(?:\.d)?/}
            || (   $file->basename =~ m{\.txt$}
                && $file->dirname =~ m{^usr/lib/python3/.*\.egg-info/}s)
            || (   $file->basename =~ m{^README}xi
                && $file->bytes =~ m{this directory}xi)
        ) {

            $self->hint('package-contains-documentation-outside-usr-share-doc',
                $file->name)
              if any { $file->basename =~ m{$_}xi }
            @DOCUMENTATION_FILE_REGEXES;
        }
    }

    if ($file->name =~ m,^usr/share/doc/\S,) {

        # file not owned by root?
        unless ($file->identity eq 'root/root' || $file->identity eq '0/0') {
            $self->hint('bad-owner-for-doc-file', $file->name, $file->identity,
                '!= root/root (or 0/0)');
        }

        # executable in /usr/share/doc ?
        if (    $file->is_file
            and $file->name !~ m,^usr/share/doc/(?:[^/]+/)?examples/,
            and ($file->operm & 0111)) {

            if ($file->is_script) {
                $self->hint('script-in-usr-share-doc', $file->name);
            } else {
                $self->hint('executable-in-usr-share-doc', $file->name,
                    (sprintf '%04o', $file->operm));
            }
        }

        # zero byte file in /usr/share/doc/
        if ($file->is_regular_file and $file->size == 0) {
            # Exceptions: examples may contain empty files for various
            # reasons, Doxygen generates empty *.map files, and Python
            # uses __init__.py to mark module directories.
            unless ($file->name =~ m,^usr/share/doc/(?:[^/]+/)?examples/,
                or $file->name
                =~ m{^usr/share/doc/(?:.+/)?(?:doxygen|html)/.*\.map$}s
                or $file->name=~ m{^usr/share/doc/(?:.+/)?__init__\.py$}s){

                $self->hint('zero-byte-file-in-doc-directory', $file->name);
            }
        }

        # gzipped zero byte files:
        # 276 is 255 bytes (maximal length for a filename)
        # + gzip overhead
        if (    $file->name =~ m{\.gz$}
            and $file->is_regular_file
            and $file->size <= 276
            and $file->file_info =~ m/gzip compressed/) {
            my $fd = open_gz($file->unpacked_path);
            my $f = <$fd>;
            close($fd);
            unless (defined $f and length $f) {
                $self->hint('zero-byte-file-in-doc-directory', $file->name);
            }
        }
    }

    # file directly in /usr/share/doc ?
    if (    $file->is_file
        and $file->name =~ m,^usr/share/doc/[^/]+$,){
        $self->hint('file-directly-in-usr-share-doc', $file->name);
    }

    # contains an INSTALL file?
    if ($file->name =~ m{^usr/share/doc/$ppkg/INSTALL(?:\..+)*$}s){
        $self->hint('package-contains-upstream-installation-documentation',
            $file->name);
    }

    # contains a README for another distribution/platform?
    if (
        $file->name =~ m,^usr/share/doc/$ppkg/readme\.
                             (?:apple|aix|atari|be|beos|bsd|bsdi
                               |cygwin|darwin|irix|gentoo|freebsd|mac|macos
                               |macosx|netbsd|openbsd|osf|redhat|sco|sgi
                               |solaris|suse|sun|vms|win32|win9x|windows
                             )(?:\.txt)?(?:\.gz)?$,xi
    ) {
        $self->hint('package-contains-readme-for-other-platform-or-distro',
            $file->name);
    }

    # contains a compressed version of objects.inv in
    # sphinx-generated documentation?
    if (    $file->name=~ m,^usr/share/doc/$ppkg/(?:[^/]+/)+objects\.inv\.gz$,
        and $file->file_info =~ m/gzip compressed/) {
        $self->hint('compressed-documentation', $file->name);
    }

    return;
}

1;

# Local Variables:
# indent-tabs-mode: nil
# cperl-indent-level: 4
# End:
# vim: syntax=perl sw=4 sts=4 sr et
