[bugzilla-gnome-org-extensions] Create new extension - TemplateOverrides

[Krzesimir Nowak <krnowak src gnome org>]

commit 7bca25d9f06021351766cfa8242e6abfb33766ad
Author: Krzesimir Nowak <qdlacz gmail com>
Date:   Sun Nov 9 12:51:59 2014 +0100

    Create new extension - TemplateOverrides
    
    A central place where template overrides are kept and their original
    counterparts' sha256sums are checked.
    
    This is to make sure that we are overriding a known version of
    template. If sha256sum does not agree then it means that the original
    has changed and there may be some fixes to be backported to our
    overrides.

 TODO                                               |    7 -
 TemplateOverrides/Config.pm                        |   27 ++++
 TemplateOverrides/Extension.pm                     |   28 ++++
 TemplateOverrides/doc/templateoverrides.rst        |   10 ++
 TemplateOverrides/lib/Util.pm                      |  142 ++++++++++++++++++++
 TemplateOverrides/template/en/default/hook/README  |    5 +
 .../template/en/default/templateoverrides/README   |   16 +++
 TemplateOverrides/web/README                       |    7 +
 8 files changed, 235 insertions(+), 7 deletions(-)
---
diff --git a/TODO b/TODO
index 339944c..736ec50 100644
--- a/TODO
+++ b/TODO
@@ -22,13 +22,6 @@ titles work correctly.
 Idea - replace "user_cache = template_cache.users" with "user_cache =
 {}"
 
-7. New extension - TemplateOverrides
-Create a new extension that will keep all overridden templates and
-will perform the checks like GnomeAttachmentStatus is doing.
-
-The aim to to have a single place where checks are actually performed
-during checksetup.
-
 8. New extension - ExtensionDeps
 Create a new extension that will keep the data about dependencies
 between extensions. For example PatchStatus depends on
diff --git a/TemplateOverrides/Config.pm b/TemplateOverrides/Config.pm
new file mode 100644
index 0000000..e61a50c
--- /dev/null
+++ b/TemplateOverrides/Config.pm
@@ -0,0 +1,27 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# This Source Code Form is "Incompatible With Secondary Licenses", as
+# defined by the Mozilla Public License, v. 2.0.
+
+package Bugzilla::Extension::TemplateOverrides;
+
+use 5.10.1;
+use strict;
+use warnings;
+
+use constant NAME => 'TemplateOverrides';
+
+use constant REQUIRED_MODULES => [
+    {
+        'package' => 'Array-Utils',
+        'module' => 'Array::Utils',
+        'version' => 0.5
+    }
+];
+
+use constant OPTIONAL_MODULES => [
+];
+
+__PACKAGE__->NAME;
diff --git a/TemplateOverrides/Extension.pm b/TemplateOverrides/Extension.pm
new file mode 100644
index 0000000..5a6dcbb
--- /dev/null
+++ b/TemplateOverrides/Extension.pm
@@ -0,0 +1,28 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# This Source Code Form is "Incompatible With Secondary Licenses", as
+# defined by the Mozilla Public License, v. 2.0.
+
+package Bugzilla::Extension::TemplateOverrides;
+
+use 5.10.1;
+use strict;
+use warnings;
+
+use parent qw(Bugzilla::Extension);
+
+# This code for this is in ./extensions/TemplateOverrides/lib/Util.pm
+use Bugzilla::Extension::TemplateOverrides::Util;
+
+our $VERSION = '0.01';
+
+sub install_before_final_checks {
+    my ($self, $params) = @_;
+    my $silent = $params->{'silent'};
+
+    check_overridden_templates($silent);
+}
+
+__PACKAGE__->NAME;
diff --git a/TemplateOverrides/doc/templateoverrides.rst b/TemplateOverrides/doc/templateoverrides.rst
new file mode 100644
index 0000000..0e8f321
--- /dev/null
+++ b/TemplateOverrides/doc/templateoverrides.rst
@@ -0,0 +1,10 @@
+TemplateOverrides
+#################
+
+This is a sample documentation file for the TemplateOverrides extension. Like all of
+the Bugzilla docs, it's written in
+`reStructured Text (reST) format <http://sphinx-doc.org/latest/rest.html>`_
+and will be compiled by `Sphinx <http://sphinx-doc.org/>`_.
+
+If you build the docs yourself using :file:`makedocs.pl`, this file will get
+incorporated into the Extensions chapter.
\ No newline at end of file
diff --git a/TemplateOverrides/lib/Util.pm b/TemplateOverrides/lib/Util.pm
new file mode 100644
index 0000000..c546027
--- /dev/null
+++ b/TemplateOverrides/lib/Util.pm
@@ -0,0 +1,142 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# This Source Code Form is "Incompatible With Secondary Licenses", as
+# defined by the Mozilla Public License, v. 2.0.
+
+package Bugzilla::Extension::TemplateOverrides::Util;
+
+use 5.10.1;
+use strict;
+use warnings;
+use parent qw(Exporter);
+use Array::Utils qw(array_minus intersect);
+use IO::Dir;
+use File::Spec;
+
+our @EXPORT = qw(
+    check_overridden_templates
+);
+
+# This file can be loaded by your extension via
+# "use Bugzilla::Extension::TemplateOverrides::Util". You can put functions
+# used by your extension in here. (Make sure you also list them in
+# @EXPORT.)
+
+sub _get_templates {
+    my (@initial_paths) = @_;
+    my @paths = map {[$_, undef]} @initial_paths;
+    my @tmpls = ();
+
+    while (@paths) {
+        my $path_pair = shift(@paths);
+        my $initial = $path_pair->[0];
+        my $rest = $path_pair->[1];
+        my $path = $initial;
+
+        if (defined($rest)) {
+            $path = File::Spec->catdir($initial, $rest);
+        }
+
+        my $dir = IO::Dir->new($path);
+
+        next unless defined($dir);
+        while (defined(my $entry = $dir->read())) {
+            next if $entry =~ /^\.{1,2}$/;
+
+            my $rest_entry = $entry;
+
+            if (defined($rest)) {
+                $rest_entry = File::Spec->catdir($rest, $entry);
+            }
+
+            my $complete_path = File::Spec->catdir($initial, $rest_entry);
+
+            if (-d $complete_path) {
+                push(@paths, [$initial, $rest_entry]);
+                next;
+            }
+            if ($entry =~ /\.tmpl$/) {
+                push(@tmpls, $rest_entry);
+                next;
+            }
+        }
+    }
+
+    @tmpls;
+}
+
+sub _check_overrides {
+    my ($extension_paths, $default_paths, $digests) = @_;
+    my @overridden = _get_templates(@{$extension_paths});
+    my @default = _get_templates(@{$default_paths});
+    my @common = intersect(@default, @overridden);
+    my @not_overrides = array_minus(@overridden, @common);
+
+    if (@not_overrides) {
+        die 'Following templates are not overriding ' .
+            'anything: ' . join(', ', @not_overrides);
+    }
+
+    my @digested_files = keys(%{$digests});
+    my @not_digested = array_minus(@overridden, @digested_files);
+
+    if (@not_digested) {
+        die 'Following overrides are missing their digests: ' .
+            join(', ', @not_digested);
+    }
+
+    my @digested_not_overrides = array_minus(@digested_files, @overridden);
+
+    if (@digested_not_overrides) {
+        die 'Following files have digests, but no overrides for them exist: ' .
+            join(', ', @digested_not_overrides);
+    }
+}
+
+sub check_overridden_templates {
+    my ($silent) = @_;
+    my %digests = (
+    );
+
+    print "Checking overridden templates...\n" unless $silent;
+    return unless keys(%digests);
+    # template_include_path is from Bugzilla::Install::Util package.
+    my @template_paths = map {File::Spec->canonpath($_)} @{Bugzilla::Install::Util::template_include_path()};
+    my @extension_paths = grep {/^extensions\/TemplateOverrides\//} @template_paths;
+    my @default_paths = grep {!/^extensions\//} @template_paths;
+
+    _check_overrides(\ extension_paths, \ default_paths, \%digests);
+    for my $file (sort keys (%digests))
+    {
+        my $complete_path = undef;
+
+        for my $path (@default_paths)
+        {
+            my $potential_path = File::Spec->catfile($path, $file);
+
+            next unless (-r $potential_path);
+            $complete_path = $potential_path;
+            last;
+        }
+        unless ($complete_path)
+        {
+            die "Original template for $file not found - should not happen";
+        }
+
+        my $sha = Digest::SHA->new(256);
+        $sha->addfile($complete_path);
+        my $digest = $sha->hexdigest();
+        if ($digest ne $digests{$file})
+        {
+            die "Original $file (at $complete_path) has changed " .
+            'since last checksetup. Please check if the changes ' .
+            'should be backported to overridden templates and ' .
+            'update the digest in %digests variable with ' .
+            $digest;
+        }
+    }
+}
+
+1;
diff --git a/TemplateOverrides/template/en/default/hook/README 
b/TemplateOverrides/template/en/default/hook/README
new file mode 100644
index 0000000..e6c4add
--- /dev/null
+++ b/TemplateOverrides/template/en/default/hook/README
@@ -0,0 +1,5 @@
+Template hooks go in this directory. Template hooks are called in normal
+Bugzilla templates like [% Hook.process('some-hook') %].
+More information about them can be found in the documentation of 
+Bugzilla::Extension. (Do "perldoc Bugzilla::Extension" from the main
+Bugzilla directory to see that documentation.)
\ No newline at end of file
diff --git a/TemplateOverrides/template/en/default/templateoverrides/README 
b/TemplateOverrides/template/en/default/templateoverrides/README
new file mode 100644
index 0000000..9022000
--- /dev/null
+++ b/TemplateOverrides/template/en/default/templateoverrides/README
@@ -0,0 +1,16 @@
+Normal templates go in this directory. You can load them in your
+code like this:
+
+use Bugzilla::Error;
+my $template = Bugzilla->template;
+$template->process('templateoverrides/some-template.html.tmpl')
+  or ThrowTemplateError($template->error());
+
+That would be how to load a file called <kbd>some-template.html.tmpl</kbd> that
+was in this directory.
+
+Note that you have to be careful that the full path of your template
+never conflicts with a template that exists in Bugzilla or in 
+another extension, or your template might override that template. That's why
+we created this directory called 'templateoverrides' for you, so you
+can put your templates in here to help avoid conflicts.
\ No newline at end of file
diff --git a/TemplateOverrides/web/README b/TemplateOverrides/web/README
new file mode 100644
index 0000000..2345641
--- /dev/null
+++ b/TemplateOverrides/web/README
@@ -0,0 +1,7 @@
+Web-accessible files, like JavaScript, CSS, and images go in this
+directory. You can reference them directly in your HTML. For example,
+if you have a file called "style.css" and your extension is called
+"Foo", you would put it in "extensions/Foo/web/style.css", and then
+you could link to it in HTML like:
+
+<link href="extensions/Foo/web/style.css" rel="stylesheet" type="text/css">
\ No newline at end of file