ci-license-scan: Insert fixup paragraphs in order of broadness

Inserting fixup paragraphs at the end of the file violates the Debian
standard ordering, where copyright paragrahs are ordered from least to
most specific. In order to fix this, we can define the "broadness" of
each Files pattern in a paragrahs, then split up the paragraph and
insert into the copyright file at positions that maintain the
broadness ordering.

Fixes apertis-issues#519.

Signed-off-by: Ryan Gonzalez <ryan.gonzalez@collabora.com>

package-source-builder/overlay/usr/bin/ci-license-scan

@@ -355,6 +355,9 @@ class MutableCopyright(Copyright):
 
 CopyrightEntry = namedtuple('CopyrightEntry', ['file', 'license'])
 
+def get_pattern_broadness(pattern):
+    return pattern.count('*') + pattern.count('?')
+
 def main():
     parser = argparse.ArgumentParser()
     parser.add_argument('--fail-on-change', dest='fail_on_change', action='store_true', default=False, help='fail on any changes')
@@ -423,17 +426,40 @@ def main():
         if fixups:
             for fc, fls in fixups.items():
                 for fl, fps in fls.items():
-                    files = sorted(set(chain.from_iterable([fp.files for fp in fps])))
                     for fp in fps:
                         if fp in c.paragraphs:
                             c.paragraphs.remove(fp)
-                    new_p = FilesParagraph.create(
-                        files=files,
-                        copyright=reindent_multiline(fc),
-                        license=fl
-                    )
-                    c.add_files_paragraph(new_p)
-                    fixups_applied.update(files)
+
+                    # Files paragraphs need to be sorted from least to most specific:
+                    # https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#files-field
+                    # We can roughly describe how specific a paragraph's Files patterns
+                    # are by the number of wildcards inside as its "broadness". This is
+                    # used to split the patterns by their broadness into groups, then a
+                    # new FilesParagraph is created and inserted for each group.
+                    grouped_by_broadness = {}
+                    for file_pattern in set(chain.from_iterable(fp.files for fp in fps)):
+                        broadness = get_pattern_broadness(file_pattern)
+                        grouped_by_broadness.setdefault(broadness, set()).add(file_pattern)
+
+                    for broadness, files in sorted(grouped_by_broadness.items(),
+                        key=lambda p: p[0],
+                        reverse=True,
+                    ):
+                        new_p = FilesParagraph.create(
+                            files=sorted(files),
+                            copyright=reindent_multiline(fc),
+                            license=fl
+                        )
+                        # Place the new paragraph right before the next most specific
+                        # paragraph, so that they're ordered from most to least broad.
+                        for i, paragraph in enumerate(c.paragraphs):
+                            if max(map(get_pattern_broadness, paragraph.files)) < broadness:
+                                c.paragraphs.insert(i, new_p)
+                                break
+                        else:
+                            c.add_files_paragraph(new_p)
+
+                        fixups_applied.update(files)
             print(f"Reused licensing information from debian/copyright for:\n",
                 textwrap.indent("\n".join(sorted(fixups_applied)), " "*2),
                 file=sys.stderr)