From a3f7254b6385c56de446992df6823f47f4276e6f Mon Sep 17 00:00:00 2001
From: Jordan Layfield <layfield@ccdc.cam.ac.uk>
Date: Wed, 21 Oct 2026 11:16:40 +0100
Subject: [PATCH 1/4] Add BOM handling for region directives and corresponding
 tests NO_JIRA

---
 main/licence_headers.py      | 12 ++++++++----
 test/test_licence_headers.py |  8 ++++++++
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/main/licence_headers.py b/main/licence_headers.py
index 93cba62..348187a 100644
--- a/main/licence_headers.py
+++ b/main/licence_headers.py
@@ -109,24 +109,28 @@ def _header_line_matches(actual, expected):
     return actual == expected
 
 
+def _strip_bom(line):
+    return line.lstrip('\ufeff')
+
+
 def _is_region_directive(line):
-    return bool(re.match(r'^#region(?:\s|$)', line.strip()))
+    return bool(re.match(r'^#region(?:\s|$)', _strip_bom(line).strip()))
 
 
 def _is_end_region_directive(line):
-    return bool(re.match(r'^#endregion(?:\s|$)', line.strip()))
+    return bool(re.match(r'^#endregion(?:\s|$)', _strip_bom(line).strip()))
 
 
 def _find_leading_region_block(lines):
     for idx, line in enumerate(lines):
-        stripped = line.strip()
+        stripped = _strip_bom(line).strip()
         if not stripped:
             continue
         if not _is_region_directive(stripped):
             return None
         depth = 0
         for region_idx in range(idx, len(lines)):
-            region_line = lines[region_idx].strip()
+            region_line = _strip_bom(lines[region_idx]).strip()
             if _is_region_directive(region_line):
                 depth += 1
             elif _is_end_region_directive(region_line):
diff --git a/test/test_licence_headers.py b/test/test_licence_headers.py
index d4a8b27..ffaf880 100644
--- a/test/test_licence_headers.py
+++ b/test/test_licence_headers.py
@@ -29,6 +29,14 @@ def test_header_inside_leading_region_wrapper_passes_without_duplication():
     assert fixed == content
 
 
+def test_bom_before_leading_region_wrapper_is_ignored():
+    header = licence_headers._render_header('slash', year=2026)
+    content = '\ufeff#region Licence\n' + header + '#endregion\nprint("ok")\n'
+    assert licence_headers.check_content('example.cs', content, 2026) is None
+    fixed = licence_headers.fix_content('example.cs', content, 2026)
+    assert fixed == content
+
+
 def test_regional_keyword_is_not_treated_as_region_directive():
     header = licence_headers._render_header('hash', year=2026)
     content = '#regional\n' + header + 'print("ok")\n'

From 94494743ba7b40775cf5e142b7a4a1b47b71ab91 Mon Sep 17 00:00:00 2001
From: Jordan Layfield <layfield@ccdc.cam.ac.uk>
Date: Thu, 22 Oct 2026 15:25:25 +0100
Subject: [PATCH 2/4] Enhance header detection and repair logic for
 region-wrapped headers in C# and Python NO_JIRA

---
 README.md                    |  14 ++
 main/licence_headers.py      | 467 +++++++++++++++++++++--------------
 test/test_licence_headers.py | 109 +++++++-
 3 files changed, 402 insertions(+), 188 deletions(-)

diff --git a/README.md b/README.md
index 381a600..a249de6 100644
--- a/README.md
+++ b/README.md
@@ -177,6 +177,20 @@ When licence header validation/formatting is enabled, files are filtered using t
   * Suffixes: `.designer.cs`, `.g.cs`, `.min.js`, `.lock`
   * Any file containing `.generated.` in its name
 
+### Header Detection
+
+* The header may appear anywhere in the file's leading preamble (blank lines, comments,
+  region directives, and directives such as C# `using`/`#nullable`/`#pragma`, `#pragma once`
+  or `'use strict'`) before the first line of code.
+* Matching ignores comment markers, whitespace, line wrapping and marker-only (`//` or `#`)
+  padding lines, and accepts any copyright year.
+* Headers wrapped in regions are supported for C# (`#region`/`#endregion`) and Python
+  (`#region`/`# region`). Further languages can be added to `REGION_SYNTAX` in
+  `main/licence_headers.py`.
+* In fix mode, damaged headers are repaired in place, duplicate headers are removed, and a
+  missing header is inserted inside a region labelled `Licence`/`License`/`Copyright`/`Header`
+  if one exists, otherwise at the top of the file (after any shebang or encoding line).
+
 ## Recommended settings
 ### To ensure the line endings are correctly converted:
 1. On Windows: `git config --global core.autocrlf true`
diff --git a/main/licence_headers.py b/main/licence_headers.py
index 348187a..10625a3 100644
--- a/main/licence_headers.py
+++ b/main/licence_headers.py
@@ -18,7 +18,9 @@
 
 import argparse
 import codecs
+from dataclasses import dataclass
 from datetime import datetime
+from difflib import SequenceMatcher
 from io import BytesIO
 from pathlib import Path, PurePosixPath
 import re
@@ -39,6 +41,61 @@
     r'^(#|//) Copyright The Cambridge Crystallographic Data Centre '
     r'\(CCDC\) \d{4}(?:, \d{4})?\r?\n?$'
 )
+COMMENT_MARKERS = {'hash': '#', 'slash': '//'}
+YEAR_TOKEN = '{{ .Year }}'
+YEAR_PATTERN = r'\d{4}(?:, \d{4})?'
+IDENTITY_PREFIX = 'This code is'
+IDENTITY_OWNER = 'Crystallographic Data Centre (CCDC)'
+LICENCE_REGION_LABEL = re.compile(r'licen[cs]e|copyright|header', re.IGNORECASE)
+
+# Region open/close directives per file extension. To support another
+# language, add its extension with (open pattern, close pattern); the open
+# pattern may capture a "label" group used to find a licence region.
+REGION_SYNTAX = {
+    '.cs': (
+        re.compile(r'^\s*#region\b(?P<label>.*)$'),
+        re.compile(r'^\s*#endregion\b'),
+    ),
+    '.py': (
+        re.compile(r'^\s*#\s?region\b(?P<label>.*)$'),
+        re.compile(r'^\s*#\s?endregion\b'),
+    ),
+}
+
+# Non-comment lines that may legitimately appear before the licence header.
+PREAMBLE_DIRECTIVES = {
+    '.cs': (
+        re.compile(r'^\s*(?:global\s+)?using\s+(?:static\s+)?[\w.]+(?:\s*=\s*[\w.<>, ]+)?\s*;\s*$'),
+        re.compile(r'^\s*#\s*(?:nullable|pragma|define|undef)\b'),
+    ),
+    '.js': (re.compile(r'''^\s*(['"])use strict\1;?\s*$'''),),
+    '.ts': (re.compile(r'''^\s*(['"])use strict\1;?\s*$'''),),
+    '.cpp': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
+    '.cxx': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
+    '.cc': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
+    '.h': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
+    '.hpp': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
+    '.yaml': (re.compile(r'^---\s*$'),),
+    '.yml': (re.compile(r'^---\s*$'),),
+}
+
+# Damaged header recovery tolerances.
+ALIGNMENT_LOOKAHEAD = 3
+MAX_UNMATCHED_LINES = 2
+
+
+@dataclass
+class _Line:
+    kind: str  # blank, comment, region_open, region_close, directive, shebang, code
+    text: str = ''
+    label: str = ''
+
+
+@dataclass
+class _HeaderSpan:
+    start: int
+    end: int
+    valid: bool
 
 
 def _comment_style(filename):
@@ -55,10 +112,16 @@ def _comment_style(filename):
     return None
 
 
+def _suffix(filename):
+    return PurePosixPath(str(filename).replace('\\', '/')).suffix.lower()
+
+
+def _read_template(style):
+    return (TEMPLATE_DIRECTORY / f'ccdc_{style}.tmpl').read_text(encoding='utf-8')
+
+
 def _render_header(style, newline='\n', year=None):
-    template_path = TEMPLATE_DIRECTORY / f'ccdc_{style}.tmpl'
-    template = template_path.read_text(encoding='utf-8')
-    rendered = template.replace('{{ .Year }}', str(year or datetime.now().year))
+    rendered = _read_template(style).replace(YEAR_TOKEN, str(year or datetime.now().year))
     return rendered.replace('\n', newline)
 
 
@@ -74,7 +137,180 @@ def _decode_content(filename, data):
     return data.decode(encoding), encoding
 
 
-def _header_offset(filename, text, style):
+def _normalise(text):
+    return ' '.join(text.split())
+
+
+def _comment_text(line, marker):
+    '''Return the comment body of `line`, or None when it is not a comment.'''
+    stripped = line.lstrip('\ufeff').strip()
+    if not stripped.startswith(marker):
+        return None
+    return _normalise(stripped[len(marker):])
+
+
+def _template_lines(style):
+    '''Template body lines with comment markers removed and marker-only lines dropped.'''
+    marker = COMMENT_MARKERS[style]
+    texts = (_comment_text(line, marker) for line in _read_template(style).splitlines())
+    return [text for text in texts if text]
+
+
+def _header_pattern(style):
+    '''Regex matching the normalised header text with any valid year.'''
+    escaped = re.escape(' '.join(_template_lines(style)))
+    return re.compile(escaped.replace(re.escape(YEAR_TOKEN), YEAR_PATTERN))
+
+
+def _classify(filename, style, lines):
+    '''Classify the leading preamble lines; classification stops at the first code line.'''
+    marker = COMMENT_MARKERS[style]
+    region_open, region_close = REGION_SYNTAX.get(_suffix(filename), (None, None))
+    directives = PREAMBLE_DIRECTIVES.get(_suffix(filename), ())
+    classified = []
+    for index, raw in enumerate(lines):
+        line = raw.lstrip('\ufeff').rstrip('\r\n')
+        if not line.strip():
+            classified.append(_Line('blank'))
+            continue
+        if index == 0 and line.startswith('#!'):
+            classified.append(_Line('shebang'))
+            continue
+        open_match = region_open.match(line) if region_open else None
+        if open_match:
+            classified.append(_Line('region_open', label=open_match.group('label').strip()))
+            continue
+        if region_close and region_close.match(line):
+            classified.append(_Line('region_close'))
+            continue
+        text = _comment_text(line, marker)
+        if text is not None:
+            classified.append(_Line('comment', text=text))
+            continue
+        if any(pattern.match(line) for pattern in directives):
+            classified.append(_Line('directive'))
+            continue
+        classified.append(_Line('code'))
+        break
+    return classified
+
+
+def _is_marker_only(line):
+    return line.kind == 'comment' and not line.text
+
+
+def _comment_runs(classified):
+    run = []
+    for index, line in enumerate(classified):
+        if line.kind == 'comment':
+            run.append(index)
+        elif run:
+            yield run
+            run = []
+    if run:
+        yield run
+
+
+def _find_valid_headers(classified, pattern):
+    '''Find complete headers by matching normalised text within contiguous comment runs.'''
+    spans = []
+    for run in _comment_runs(classified):
+        parts, starts, ends = [], {}, {}
+        position = 0
+        for index in run:
+            text = classified[index].text
+            if not text:
+                continue
+            if parts:
+                position += 1
+            starts[position] = index
+            ends[position + len(text)] = index
+            parts.append(text)
+            position += len(text)
+        for match in pattern.finditer(' '.join(parts)):
+            if match.start() not in starts or match.end() not in ends:
+                continue
+            start, end = starts[match.start()], ends[match.end()] + 1
+            if start > 0 and _is_marker_only(classified[start - 1]) and not _claimed(spans, start - 1):
+                start -= 1
+            if end < len(classified) and _is_marker_only(classified[end]):
+                end += 1
+            spans.append(_HeaderSpan(start, end, valid=True))
+    return spans
+
+
+def _claimed(spans, index):
+    return any(span.start <= index < span.end for span in spans)
+
+
+def _similar(actual, expected):
+    if actual == expected:
+        return True
+    matcher = SequenceMatcher(None, actual, expected, autojunk=False)
+    longest = matcher.find_longest_match(0, len(actual), 0, len(expected)).size
+    return (longest >= 6 and longest >= len(actual) / 2) or matcher.ratio() >= 0.75
+
+
+def _align(text, expected, pointer):
+    '''Return the template line index `text` corresponds to, scanning forward from `pointer`.'''
+    for index in range(pointer, min(pointer + ALIGNMENT_LOOKAHEAD, len(expected))):
+        if _similar(text, expected[index]):
+            return index
+    if pointer < len(expected) and text == expected[-1]:
+        return len(expected) - 1
+    return None
+
+
+def _damaged_span(classified, anchor, expected, claimed):
+    '''Extend a damaged header from its identity line while lines still resemble the template.'''
+    start = anchor
+    if anchor > 0 and _is_marker_only(classified[anchor - 1]) and not _claimed(claimed, anchor - 1):
+        start -= 1
+    pointer, end, unmatched = 1, anchor + 1, 0
+    index = anchor + 1
+    while index < len(classified) and pointer < len(expected) and not _claimed(claimed, index):
+        line = classified[index]
+        if line.kind == 'blank' or _is_marker_only(line):
+            index += 1
+            continue
+        if line.kind != 'comment':
+            break
+        aligned = _align(line.text, expected, pointer)
+        if aligned is None:
+            unmatched += 1
+            if unmatched > MAX_UNMATCHED_LINES:
+                break
+        else:
+            pointer, end, unmatched = aligned + 1, index + 1, 0
+        index += 1
+    if end < len(classified) and _is_marker_only(classified[end]) and not _claimed(claimed, end):
+        end += 1
+    return _HeaderSpan(start, end, valid=False)
+
+
+def _find_headers(filename, style, lines):
+    classified = _classify(filename, style, lines)
+    spans = _find_valid_headers(classified, _header_pattern(style))
+    expected = _template_lines(style)
+    for index, line in enumerate(classified):
+        if _claimed(spans, index):
+            continue
+        if LEGACY_HEADER_PATTERN.match(lines[index].lstrip('\ufeff')):
+            end = index + 1
+            if end < len(classified) and classified[end].kind == 'blank':
+                end += 1
+            spans.append(_HeaderSpan(index, end, valid=False))
+        elif (
+            line.kind == 'comment'
+            and line.text.startswith(IDENTITY_PREFIX)
+            and IDENTITY_OWNER in line.text
+        ):
+            spans.append(_damaged_span(classified, index, expected, spans))
+    return sorted(spans, key=lambda span: span.start), classified
+
+
+def _header_offset(filename, text):
+    '''Character offset where a missing header is inserted at the top of the file.'''
     lines = text.splitlines(keepends=True)
     has_shebang = bool(lines and lines[0].startswith('#!'))
     if not str(filename).lower().endswith('.py'):
@@ -97,168 +333,26 @@ def _header_offset(filename, text, style):
     return len(lines[0]) if has_shebang else 0
 
 
-def _header_line_matches(actual, expected):
-    if 'This code is Copyright (C)' in expected:
-        marker = expected.split(' ', 1)[0]
-        pattern = (
-            rf'{re.escape(marker)} This code is Copyright \(C\) '
-            r'\d{4}(?:, \d{4})? '
-            r'The Cambridge Crystallographic Data Centre \(CCDC\)'
-        )
-        return re.fullmatch(pattern, actual) is not None
-    return actual == expected
-
-
-def _strip_bom(line):
-    return line.lstrip('\ufeff')
-
-
-def _is_region_directive(line):
-    return bool(re.match(r'^#region(?:\s|$)', _strip_bom(line).strip()))
-
-
-def _is_end_region_directive(line):
-    return bool(re.match(r'^#endregion(?:\s|$)', _strip_bom(line).strip()))
-
-
-def _find_leading_region_block(lines):
-    for idx, line in enumerate(lines):
-        stripped = _strip_bom(line).strip()
-        if not stripped:
-            continue
-        if not _is_region_directive(stripped):
-            return None
-        depth = 0
-        for region_idx in range(idx, len(lines)):
-            region_line = _strip_bom(lines[region_idx]).strip()
-            if _is_region_directive(region_line):
-                depth += 1
-            elif _is_end_region_directive(region_line):
-                depth -= 1
-                if depth == 0:
-                    return idx, region_idx
-        return None
-    return None
-
-
-def _strip_leading_region_wrapper(text):
-    lines = text.splitlines()
-    region_block = _find_leading_region_block(lines)
-    if region_block is None:
-        return lines
-    idx, region_end = region_block
-    return lines[idx + 1:region_end]
-
-
-def _known_header_prefix_end(text, offset, expected):
-    actual_lines = []
-    position = offset
-    for line in text[offset:].splitlines(keepends=True):
-        actual_lines.append((position, position + len(line), line.strip()))
-        position += len(line)
-
-    expected_lines = [line.strip() for line in expected.splitlines()]
-    if not actual_lines or not expected_lines:
-        return offset
-
-    if actual_lines[0][2] == expected_lines[0] and len(actual_lines) > 1:
-        if not _header_line_matches(actual_lines[1][2], expected_lines[1]):
-            return offset
-        header_end = actual_lines[1][1]
-        start_idx = 2
-        exp_start_idx = 2
-    elif _header_line_matches(actual_lines[0][2], expected_lines[1]):
-        header_end = actual_lines[0][1]
-        start_idx = 1
-        exp_start_idx = 2
-    else:
-        return offset
-
-    for actual_idx, exp_idx in enumerate(range(exp_start_idx, len(expected_lines)), start=start_idx):
-        if actual_idx >= len(actual_lines):
-            break
-        if not _header_line_matches(actual_lines[actual_idx][2], expected_lines[exp_idx]):
-            break
-        header_end = actual_lines[actual_idx][1]
-    return header_end
-
-
-def _damaged_full_header_end(text, offset, style):
-    marker = '#' if style == 'hash' else '//'
-    lines = text[offset:].splitlines(keepends=True)
-    if not lines:
-        return offset
-
-    first_line = lines[0].strip()
-    if first_line == marker and len(lines) > 1:
-        identity_line = lines[1].strip()
-        start_index = 2
-    else:
-        identity_line = first_line
-        start_index = 1
-
-    if (
-        not identity_line.startswith(f'{marker} This code is ')
-        or 'Crystallographic Data Centre (CCDC)' not in identity_line
-    ):
-        return offset
-
-    position = offset
-    line_positions = []
-    for line in lines:
-        line_positions.append((position, position + len(line), line.strip()))
-        position += len(line)
+def _insert_header(filename, text, lines, classified, expected, newline):
+    for index, line in enumerate(classified):
+        if line.kind == 'region_open' and LICENCE_REGION_LABEL.search(line.label):
+            prefix = ''.join(lines[:index + 1])
+            if not prefix.endswith(('\n', '\r')):
+                prefix += newline
+            return prefix + expected + ''.join(lines[index + 1:])
+    offset = _header_offset(filename, text)
+    prefix = text[:offset]
+    if prefix and not prefix.endswith(('\n', '\r')):
+        prefix += newline
+    return prefix + expected + text[offset:]
 
-    for index in range(start_index, len(line_positions)):
-        _, line_end, stripped = line_positions[index]
-        if stripped and not stripped.startswith(marker):
-            break
-        if (stripped.startswith(marker) and stripped.endswith('law.')) or 'void or unenforceable under governing' in stripped:
-            if stripped.endswith('law.'):
-                if index + 1 < len(line_positions) and line_positions[index + 1][2] == marker:
-                    return line_positions[index + 1][1]
-                return line_end
-            elif index + 1 < len(line_positions) and line_positions[index + 1][2].startswith(marker) and line_positions[index + 1][2].endswith('law.'):
-                next_index = index + 1
-                if next_index + 1 < len(line_positions) and line_positions[next_index + 1][2] == marker:
-                    return line_positions[next_index + 1][1]
-                return line_positions[next_index][1]
-    return offset
-
-
-def _existing_header_end(text, offset, style, expected):
-    lines = text[offset:].splitlines(keepends=True)
-    if lines and _is_region_directive(lines[0].strip()):
-        return offset
-    if lines and LEGACY_HEADER_PATTERN.match(lines[0]):
-        if len(lines) > 1 and lines[1].strip() == '':
-            return offset + len(lines[0]) + len(lines[1])
-        return offset + len(lines[0])
-    damaged_header_end = _damaged_full_header_end(text, offset, style)
-    if damaged_header_end != offset:
-        return damaged_header_end
-    return _known_header_prefix_end(text, offset, expected)
-
-
-def _has_valid_header(text, offset, expected):
-    '''Check if text starting at offset contains a valid compliant header (accepting any valid year).'''
-    if text.startswith(expected, offset):
-        return True
 
-    body_lines = text[offset:].splitlines()
-    stripped_body = _strip_leading_region_wrapper('\n'.join(body_lines))
-    actual_lines = [line.strip() for line in stripped_body]
-    expected_lines = [line.strip() for line in expected.splitlines()]
-    if len(actual_lines) < len(expected_lines):
-        return False
-    for actual, exp in zip(actual_lines[:len(expected_lines)], expected_lines):
-        if not _header_line_matches(actual, exp):
-            return False
-    return True
+def _newline(text):
+    return '\r\n' if '\r\n' in text else '\n'
 
 
 def check_content(filename, data, year=None):
-    '''Return an error message when a supported file lacks the exact header.'''
+    '''Return an error message when a supported file lacks exactly one compliant header.'''
     style = _comment_style(filename)
     if style is None:
         return None
@@ -267,44 +361,47 @@ def check_content(filename, data, year=None):
     except (LookupError, SyntaxError, UnicodeDecodeError):
         return 'file encoding could not be decoded'
 
-    newline = '\r\n' if '\r\n' in text else '\n'
-    offset = _header_offset(filename, text, style)
-    expected = _render_header(style, newline, year)
-    if _has_valid_header(text, offset, expected):
+    spans, _ = _find_headers(filename, style, text.splitlines(keepends=True))
+    if len(spans) > 1:
+        return 'duplicate CCDC copyright and licence headers'
+    if len(spans) == 1 and spans[0].valid:
         return None
     return 'missing or non-compliant CCDC copyright and licence header'
 
 
 def fix_content(filename, data, year=None):
-    '''Return content with the full rendered header for supported files.'''
+    '''Return content with exactly one compliant header, repairing it in place.'''
     style = _comment_style(filename)
     if style is None:
         return data
 
     text, encoding = _decode_content(filename, data)
-    newline = '\r\n' if '\r\n' in text else '\n'
-    offset = _header_offset(filename, text, style)
-    expected = _render_header(style, newline, year)
-    if _has_valid_header(text, offset, expected):
+    lines = text.splitlines(keepends=True)
+    spans, classified = _find_headers(filename, style, lines)
+    if len(spans) == 1 and spans[0].valid:
         return data
 
-    lines = text.splitlines(keepends=True)
-    region_block = _find_leading_region_block(lines)
-    if region_block is not None:
-        region_start, region_end = region_block
-        inner = ''.join(lines[region_start + 1:region_end])
-        if _has_valid_header(inner, 0, expected):
-            return data
-        header_end = _existing_header_end(inner, 0, style, expected)
-        fixed_inner = expected + inner[header_end:]
-        fixed = ''.join(lines[:region_start + 1]) + fixed_inner + ''.join(lines[region_end:])
+    newline = _newline(text)
+    expected = _render_header(style, newline, year)
+    if not spans:
+        fixed = _insert_header(filename, text, lines, classified, expected, newline)
         return fixed.encode(encoding) if encoding else fixed
 
-    header_end = _existing_header_end(text, offset, style, expected)
-    prefix = text[:offset]
-    if prefix and not prefix.endswith(('\n', '\r')):
-        prefix += newline
-    fixed = prefix + expected + text[header_end:]
+    keep = next((span for span in spans if span.valid), spans[0])
+    output = []
+    index = 0
+    for span in spans:
+        output.extend(lines[index:span.start])
+        index = span.end
+        if span is keep:
+            if span.valid:
+                output.extend(lines[span.start:span.end])
+            else:
+                output.append(expected)
+        elif index < len(classified) and classified[index].kind == 'blank':
+            index += 1
+    output.extend(lines[index:])
+    fixed = ''.join(output)
     return fixed.encode(encoding) if encoding else fixed
 
 
diff --git a/test/test_licence_headers.py b/test/test_licence_headers.py
index ffaf880..e4165b1 100644
--- a/test/test_licence_headers.py
+++ b/test/test_licence_headers.py
@@ -40,9 +40,10 @@ def test_bom_before_leading_region_wrapper_is_ignored():
 def test_regional_keyword_is_not_treated_as_region_directive():
     header = licence_headers._render_header('hash', year=2026)
     content = '#regional\n' + header + 'print("ok")\n'
-    assert licence_headers.check_content('example.py', content, 2026) is not None
-    fixed = licence_headers.fix_content('example.py', content, 2026)
-    assert fixed.startswith(header)
+    assert licence_headers.check_content('example.py', content, 2026) is None
+    assert licence_headers.fix_content('example.py', content, 2026) == content
+    missing = '#regional licence\nprint("ok")\n'
+    assert licence_headers.fix_content('example.py', missing, 2026) == header + missing
 
 
 def test_wrapped_header_is_repaired_in_place_without_double_insert():
@@ -359,3 +360,105 @@ def test_process_files_skips_symlinks(tmp_path):
     # Fix mode should skip symlink without modifying target file
     assert licence_headers.process_files([str(symlink)], fix=True, year=2026) == 0
     assert target.read_text(encoding='utf-8') == target_content
+
+
+SLASH_HEADER = licence_headers._render_header('slash', year=2024)
+SLASH_UNPADDED = ''.join(line for line in SLASH_HEADER.splitlines(keepends=True) if line.strip() != '//')
+CS_BODY = 'namespace Ccdc.Example\n{\n    public class Foo { }\n}\n'
+
+
+def _assert_stable(filename, content):
+    fixed = licence_headers.fix_content(filename, content, 2026)
+    assert licence_headers.check_content(filename, fixed, 2026) is None
+    assert licence_headers.fix_content(filename, fixed, 2026) == fixed
+    assert fixed.count('This code is Copyright') == 1
+    return fixed
+
+
+def test_cs_header_in_region_with_surrounding_blank_lines_passes():
+    content = '#region Licence\n\n' + SLASH_HEADER + '\n#endregion\n\n' + CS_BODY
+    assert licence_headers.check_content('Foo.cs', content, 2026) is None
+    assert licence_headers.fix_content('Foo.cs', content, 2026) == content
+
+
+def test_cs_header_after_usings_and_directives_passes():
+    content = (
+        '// <auto-generated-ish note>\n#nullable enable\nusing System;\nusing IO = System.IO;\n\n'
+        '  #region Copyright\n' + SLASH_HEADER + '  #endregion\n' + CS_BODY
+    )
+    assert licence_headers.check_content('Foo.cs', content, 2026) is None
+    assert licence_headers.fix_content('Foo.cs', content, 2026) == content
+
+
+def test_header_without_marker_padding_lines_passes():
+    for content in [SLASH_UNPADDED + CS_BODY, '#region Licence\n' + SLASH_UNPADDED + '#endregion\n' + CS_BODY]:
+        assert licence_headers.check_content('Foo.cs', content, 2026) is None
+        assert licence_headers.fix_content('Foo.cs', content, 2026) == content
+
+
+def test_crlf_header_in_region_passes():
+    content = ('#region Licence\n' + SLASH_HEADER + '#endregion\n' + CS_BODY).replace('\n', '\r\n')
+    assert licence_headers.check_content('Foo.cs', content, 2026) is None
+    assert licence_headers.fix_content('Foo.cs', content, 2026) == content
+
+
+def test_damaged_header_in_region_after_preamble_is_repaired_in_place():
+    damaged = SLASH_HEADER.replace('// may NOT be disclosed or redistributed in any form, either in whole or in\n', '')
+    content = 'using System;\n\n#region Licence\n\n' + damaged + '\n#endregion\n' + CS_BODY
+    fixed = _assert_stable('Foo.cs', content)
+    expected_header = licence_headers._render_header('slash', year=2026)
+    assert fixed == 'using System;\n\n#region Licence\n\n' + expected_header + '\n#endregion\n' + CS_BODY
+
+
+def test_stacked_duplicate_headers_fail_and_collapse_to_one():
+    region = '#region Licence\n' + SLASH_HEADER + '#endregion\n'
+    for content in [
+        SLASH_HEADER + region + CS_BODY,
+        SLASH_HEADER + '\n' + SLASH_HEADER + '\n' + SLASH_UNPADDED + CS_BODY,
+    ]:
+        assert 'duplicate' in licence_headers.check_content('Foo.cs', content, 2026)
+        fixed = _assert_stable('Foo.cs', content)
+        assert fixed.endswith(CS_BODY)
+        assert 'Copyright (C) 2024' in fixed
+
+
+def test_damaged_duplicate_is_removed_and_valid_header_kept():
+    damaged = '// This code is Copyright (C) 2020 The Cambridge Crystallographic Data Centre (CCDC)\n// of 12 Union\n'
+    content = damaged + '#region Licence\n' + SLASH_HEADER + '#endregion\n' + CS_BODY
+    fixed = _assert_stable('Foo.cs', content)
+    assert fixed == '#region Licence\n' + SLASH_HEADER + '#endregion\n' + CS_BODY
+
+
+def test_missing_header_is_inserted_into_empty_licence_region():
+    content = 'using System;\n#region License\n#endregion\n' + CS_BODY
+    fixed = _assert_stable('Foo.cs', content)
+    expected_header = licence_headers._render_header('slash', year=2026)
+    assert fixed == 'using System;\n#region License\n' + expected_header + '#endregion\n' + CS_BODY
+
+
+def test_missing_header_ignores_unrelated_region():
+    content = '#region Imports\nusing System;\n#endregion\n' + CS_BODY
+    fixed = _assert_stable('Foo.cs', content)
+    assert fixed == licence_headers._render_header('slash', year=2026) + content
+
+
+def test_header_after_code_is_not_accepted():
+    content = CS_BODY + SLASH_HEADER
+    assert licence_headers.check_content('Foo.cs', content, 2026) is not None
+    fixed = licence_headers.fix_content('Foo.cs', content, 2026)
+    assert fixed.startswith(licence_headers._render_header('slash', year=2026) + CS_BODY)
+
+
+def test_repeated_fix_never_adds_headers():
+    samples = [
+        '#region Licence\n\n' + SLASH_HEADER + '#endregion\n' + CS_BODY,
+        '\ufeffusing System;\n\n#region Licence\n' + SLASH_UNPADDED + '\n#endregion\n' + CS_BODY,
+        '#region Licence\n#endregion\n' + CS_BODY,
+        CS_BODY,
+    ]
+    for content in samples:
+        fixed = content
+        for _ in range(3):
+            fixed = licence_headers.fix_content('Foo.cs', fixed, 2026)
+        assert fixed.count('This code is Copyright') == 1
+        assert licence_headers.check_content('Foo.cs', fixed, 2026) is None

From af44d35a342b9d4e96dd8011949748a87ab9b595 Mon Sep 17 00:00:00 2001
From: Jordan Layfield <layfield@ccdc.cam.ac.uk>
Date: Thu, 22 Oct 2026 15:26:28 +0100
Subject: [PATCH 3/4] Fix encoding for fixed content in licence header
 processing NO_JIRA

---
 main/licence_headers.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/main/licence_headers.py b/main/licence_headers.py
index 10625a3..5d047e7 100644
--- a/main/licence_headers.py
+++ b/main/licence_headers.py
@@ -417,6 +417,8 @@ def process_files(files, fix=False, year=None):
             continue
         if fix:
             fixed = fix_content(filename, data, year)
+            if isinstance(fixed, str):
+                fixed = fixed.encode('utf-8')
             if fixed != data:
                 path.write_bytes(fixed)
                 print(f'Updated CCDC licence header: {filename}')

From df34fb1e81556a4a4f8490d58f9dc02ea235bb80 Mon Sep 17 00:00:00 2001
From: Jordan Layfield <layfield@ccdc.cam.ac.uk>
Date: Thu, 22 Oct 2026 16:59:47 +0100
Subject: [PATCH 4/4] Enhance header processing and recovery logic for various
 edge cases in licence header checks and tests NO_JIRA

---
 main/licence_headers.py      | 226 ++++++++++++++++++++++++++---------
 test/test_licence_headers.py | 121 +++++++++++++++++++
 2 files changed, 288 insertions(+), 59 deletions(-)

diff --git a/main/licence_headers.py b/main/licence_headers.py
index 5d047e7..a0bc6c1 100644
--- a/main/licence_headers.py
+++ b/main/licence_headers.py
@@ -21,6 +21,7 @@
 from dataclasses import dataclass
 from datetime import datetime
 from difflib import SequenceMatcher
+from functools import lru_cache
 from io import BytesIO
 from pathlib import Path, PurePosixPath
 import re
@@ -37,6 +38,7 @@
 IGNORED_SUFFIXES = ('.designer.cs', '.g.cs', '.min.js', '.lock')
 TEMPLATE_DIRECTORY = Path(__file__).resolve().parent / 'headers'
 PYTHON_ENCODING_PATTERN = re.compile(r'^[ \t\f]*#.*?coding[:=][ \t]*[-\w.]+')
+PYTHON_BLANK_OR_COMMENT_PATTERN = re.compile(r'^[ \t\f]*(?:[#\r\n]|$)')
 LEGACY_HEADER_PATTERN = re.compile(
     r'^(#|//) Copyright The Cambridge Crystallographic Data Centre '
     r'\(CCDC\) \d{4}(?:, \d{4})?\r?\n?$'
@@ -47,6 +49,7 @@
 IDENTITY_PREFIX = 'This code is'
 IDENTITY_OWNER = 'Crystallographic Data Centre (CCDC)'
 LICENCE_REGION_LABEL = re.compile(r'licen[cs]e|copyright|header', re.IGNORECASE)
+DECODE_ERROR = 'file encoding could not be decoded'
 
 # Region open/close directives per file extension. To support another
 # language, add its extension with (open pattern, close pattern); the open
@@ -63,25 +66,29 @@
 }
 
 # Non-comment lines that may legitimately appear before the licence header.
+TRAILING_SLASH_COMMENT = r'\s*(?://.*|/\*.*?\*/\s*)?$'
+USE_STRICT = re.compile(r'''^\s*(['"])use strict\1;?''' + TRAILING_SLASH_COMMENT)
+PRAGMA_ONCE = re.compile(r'^\s*#\s*pragma\s+once\b')
+YAML_DOCUMENT_START = re.compile(r'^---\s*$')
 PREAMBLE_DIRECTIVES = {
     '.cs': (
-        re.compile(r'^\s*(?:global\s+)?using\s+(?:static\s+)?[\w.]+(?:\s*=\s*[\w.<>, ]+)?\s*;\s*$'),
+        re.compile(
+            r'^\s*(?:global\s+)?using\s+(?:static\s+)?[\w.]+(?:\s*=\s*[\w.<>, ]+)?\s*;'
+            + TRAILING_SLASH_COMMENT
+        ),
         re.compile(r'^\s*#\s*(?:nullable|pragma|define|undef)\b'),
     ),
-    '.js': (re.compile(r'''^\s*(['"])use strict\1;?\s*$'''),),
-    '.ts': (re.compile(r'''^\s*(['"])use strict\1;?\s*$'''),),
-    '.cpp': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
-    '.cxx': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
-    '.cc': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
-    '.h': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
-    '.hpp': (re.compile(r'^\s*#\s*pragma\s+once\b'),),
-    '.yaml': (re.compile(r'^---\s*$'),),
-    '.yml': (re.compile(r'^---\s*$'),),
+    **{suffix: (USE_STRICT,) for suffix in ('.js', '.ts')},
+    **{suffix: (PRAGMA_ONCE,) for suffix in ('.cpp', '.cxx', '.cc', '.h', '.hpp')},
+    **{suffix: (YAML_DOCUMENT_START,) for suffix in ('.yaml', '.yml')},
 }
 
-# Damaged header recovery tolerances.
+# Damaged header recovery tolerances. Jumps further than ALIGNMENT_LOOKAHEAD
+# template lines are only accepted when confirmed by a run of consecutive
+# template lines, so isolated source comments are never absorbed.
 ALIGNMENT_LOOKAHEAD = 3
 MAX_UNMATCHED_LINES = 2
+MIN_CONFIRMED_RUN = 3
 
 
 @dataclass
@@ -98,8 +105,20 @@ class _HeaderSpan:
     valid: bool
 
 
+def _path(filename):
+    return PurePosixPath(str(filename).replace('\\', '/'))
+
+
+def _suffix(filename):
+    return _path(filename).suffix.lower()
+
+
+def _is_python(filename):
+    return _suffix(filename) == '.py'
+
+
 def _comment_style(filename):
-    path = PurePosixPath(str(filename).replace('\\', '/'))
+    path = _path(filename)
     lower_name = path.name.lower()
     if any(part.lower() in IGNORED_DIRECTORIES for part in path.parts):
         return None
@@ -112,10 +131,7 @@ def _comment_style(filename):
     return None
 
 
-def _suffix(filename):
-    return PurePosixPath(str(filename).replace('\\', '/')).suffix.lower()
-
-
+@lru_cache(maxsize=None)
 def _read_template(style):
     return (TEMPLATE_DIRECTORY / f'ccdc_{style}.tmpl').read_text(encoding='utf-8')
 
@@ -130,7 +146,7 @@ def _decode_content(filename, data):
         return data, None
     if data.startswith(codecs.BOM_UTF8):
         encoding = 'utf-8-sig'
-    elif str(filename).lower().endswith('.py'):
+    elif _is_python(filename):
         encoding, _ = tokenize.detect_encoding(BytesIO(data).readline)
     else:
         encoding = 'utf-8'
@@ -149,13 +165,15 @@ def _comment_text(line, marker):
     return _normalise(stripped[len(marker):])
 
 
+@lru_cache(maxsize=None)
 def _template_lines(style):
     '''Template body lines with comment markers removed and marker-only lines dropped.'''
     marker = COMMENT_MARKERS[style]
     texts = (_comment_text(line, marker) for line in _read_template(style).splitlines())
-    return [text for text in texts if text]
+    return tuple(text for text in texts if text)
 
 
+@lru_cache(maxsize=None)
 def _header_pattern(style):
     '''Regex matching the normalised header text with any valid year.'''
     escaped = re.escape(' '.join(_template_lines(style)))
@@ -199,6 +217,10 @@ def _is_marker_only(line):
     return line.kind == 'comment' and not line.text
 
 
+def _is_padding(line):
+    return line.kind == 'blank' or _is_marker_only(line)
+
+
 def _comment_runs(classified):
     run = []
     for index, line in enumerate(classified):
@@ -231,11 +253,11 @@ def _find_valid_headers(classified, pattern):
             if match.start() not in starts or match.end() not in ends:
                 continue
             start, end = starts[match.start()], ends[match.end()] + 1
-            if start > 0 and _is_marker_only(classified[start - 1]) and not _claimed(spans, start - 1):
-                start -= 1
-            if end < len(classified) and _is_marker_only(classified[end]):
-                end += 1
-            spans.append(_HeaderSpan(start, end, valid=True))
+            spans.append(_HeaderSpan(
+                _include_leading_marker(classified, start, spans),
+                _include_trailing_marker(classified, end, spans),
+                valid=True,
+            ))
     return spans
 
 
@@ -243,6 +265,18 @@ def _claimed(spans, index):
     return any(span.start <= index < span.end for span in spans)
 
 
+def _include_leading_marker(classified, start, claimed):
+    if start > 0 and _is_marker_only(classified[start - 1]) and not _claimed(claimed, start - 1):
+        return start - 1
+    return start
+
+
+def _include_trailing_marker(classified, end, claimed):
+    while end < len(classified) and _is_marker_only(classified[end]) and not _claimed(claimed, end):
+        end += 1
+    return end
+
+
 def _similar(actual, expected):
     if actual == expected:
         return True
@@ -261,21 +295,61 @@ def _align(text, expected, pointer):
     return None
 
 
+def _template_run(classified, index, expected, template_index, claimed):
+    '''Follow consecutive template lines from `index`, which matches `expected[template_index]`.
+
+    Returns (matched line count, end line index, reached final template line, no lines skipped).
+    '''
+    count, end, pointer, strict = 0, index, template_index, True
+    while index < len(classified) and not _claimed(claimed, index):
+        line = classified[index]
+        if _is_padding(line):
+            index += 1
+            continue
+        if line.kind != 'comment':
+            break
+        aligned = pointer if count == 0 else _align(line.text, expected, pointer)
+        if aligned is None:
+            break
+        strict = strict and aligned == pointer
+        count, end, pointer = count + 1, index + 1, aligned + 1
+        index += 1
+        if pointer >= len(expected):
+            break
+    return count, end, pointer >= len(expected), strict
+
+
+def _confirmed_template_run(classified, index, expected, first_template_index, claimed):
+    '''Find a template run starting at line `index` that is long enough to trust.
+
+    Returns (template index of the first line, end line index) or None.
+    '''
+    text = classified[index].text
+    for template_index in range(first_template_index, len(expected)):
+        if not _similar(text, expected[template_index]):
+            continue
+        count, end, complete, strict = _template_run(classified, index, expected, template_index, claimed)
+        if count >= MIN_CONFIRMED_RUN or (complete and strict and count >= 2):
+            return template_index, end
+    return None
+
+
 def _damaged_span(classified, anchor, expected, claimed):
     '''Extend a damaged header from its identity line while lines still resemble the template.'''
-    start = anchor
-    if anchor > 0 and _is_marker_only(classified[anchor - 1]) and not _claimed(claimed, anchor - 1):
-        start -= 1
+    start = _include_leading_marker(classified, anchor, claimed)
     pointer, end, unmatched = 1, anchor + 1, 0
     index = anchor + 1
     while index < len(classified) and pointer < len(expected) and not _claimed(claimed, index):
         line = classified[index]
-        if line.kind == 'blank' or _is_marker_only(line):
+        if _is_padding(line):
             index += 1
             continue
         if line.kind != 'comment':
             break
         aligned = _align(line.text, expected, pointer)
+        if aligned is None:
+            jump = _confirmed_template_run(classified, index, expected, pointer, claimed)
+            aligned = jump[0] if jump is not None else None
         if aligned is None:
             unmatched += 1
             if unmatched > MAX_UNMATCHED_LINES:
@@ -283,9 +357,21 @@ def _damaged_span(classified, anchor, expected, claimed):
         else:
             pointer, end, unmatched = aligned + 1, index + 1, 0
         index += 1
-    if end < len(classified) and _is_marker_only(classified[end]) and not _claimed(claimed, end):
-        end += 1
-    return _HeaderSpan(start, end, valid=False)
+    return _HeaderSpan(start, _include_trailing_marker(classified, end, claimed), valid=False)
+
+
+def _absorb_trailing_fragment(classified, span, expected, claimed):
+    '''Mark a header invalid and extend it over leftover template lines directly after it.'''
+    index = span.end
+    while index < len(classified) and _is_padding(classified[index]):
+        index += 1
+    if index >= len(classified) or classified[index].kind != 'comment' or _claimed(claimed, index):
+        return
+    others = [other for other in claimed if other is not span]
+    fragment = _confirmed_template_run(classified, index, expected, 1, others)
+    if fragment is not None:
+        span.end = _include_trailing_marker(classified, fragment[1], others)
+        span.valid = False
 
 
 def _find_headers(filename, style, lines):
@@ -306,41 +392,39 @@ def _find_headers(filename, style, lines):
             and IDENTITY_OWNER in line.text
         ):
             spans.append(_damaged_span(classified, index, expected, spans))
+    for span in spans:
+        _absorb_trailing_fragment(classified, span, expected, spans)
     return sorted(spans, key=lambda span: span.start), classified
 
 
+def _encoding_declaration_index(text):
+    '''Index of the PEP 263 declaration Python would honour (line 1, or line 2 after a comment).'''
+    for index, line in enumerate(text.splitlines()[:2]):
+        line = line.lstrip('\ufeff')
+        if PYTHON_ENCODING_PATTERN.match(line):
+            return index
+        if not PYTHON_BLANK_OR_COMMENT_PATTERN.match(line):
+            break
+    return None
+
+
 def _header_offset(filename, text):
     '''Character offset where a missing header is inserted at the top of the file.'''
     lines = text.splitlines(keepends=True)
-    has_shebang = bool(lines and lines[0].startswith('#!'))
-    if not str(filename).lower().endswith('.py'):
-        return len(lines[0]) if has_shebang else 0
-
-    candidate_indexes = [1] if has_shebang else [0]
-    if (
-        not has_shebang
-        and len(lines) > 1
-        and (
-            lines[0].strip() == ''
-            or lines[0].lstrip().startswith('#')
-        )
-    ):
-        candidate_indexes.append(1)
-
-    for index in candidate_indexes:
-        if index < len(lines) and PYTHON_ENCODING_PATTERN.match(lines[index]):
-            return sum(len(line) for line in lines[:index + 1])
-    return len(lines[0]) if has_shebang else 0
+    protected = 1 if lines and lines[0].startswith('#!') else 0
+    if _is_python(filename):
+        declaration = _encoding_declaration_index(text)
+        if declaration is not None:
+            protected = max(protected, declaration + 1)
+    return sum(len(line) for line in lines[:protected])
 
 
 def _insert_header(filename, text, lines, classified, expected, newline):
+    offset = _header_offset(filename, text)
     for index, line in enumerate(classified):
         if line.kind == 'region_open' and LICENCE_REGION_LABEL.search(line.label):
-            prefix = ''.join(lines[:index + 1])
-            if not prefix.endswith(('\n', '\r')):
-                prefix += newline
-            return prefix + expected + ''.join(lines[index + 1:])
-    offset = _header_offset(filename, text)
+            offset = max(offset, sum(len(raw) for raw in lines[:index + 1]))
+            break
     prefix = text[:offset]
     if prefix and not prefix.endswith(('\n', '\r')):
         prefix += newline
@@ -351,6 +435,31 @@ def _newline(text):
     return '\r\n' if '\r\n' in text else '\n'
 
 
+def _keep_encoding_declaration(filename, original, fixed, newline):
+    '''Move an encoding declaration displaced by header changes back into the first two lines.'''
+    if not _is_python(filename):
+        return fixed
+    index = _encoding_declaration_index(original)
+    if index is None or _encoding_declaration_index(fixed) is not None:
+        return fixed
+    declaration = original.lstrip('\ufeff').splitlines(keepends=True)[index]
+    lines = fixed.splitlines(keepends=True)
+    for index, line in enumerate(lines):
+        if line.strip() == declaration.strip():
+            del lines[index]
+            break
+    if not declaration.endswith(('\n', '\r')):
+        declaration += newline
+    position = 1 if lines and lines[0].startswith('#!') else 0
+    lines.insert(position, declaration)
+    return ''.join(lines)
+
+
+def _finish_fix(filename, original, fixed, encoding, newline):
+    fixed = _keep_encoding_declaration(filename, original, fixed, newline)
+    return fixed.encode(encoding) if encoding else fixed
+
+
 def check_content(filename, data, year=None):
     '''Return an error message when a supported file lacks exactly one compliant header.'''
     style = _comment_style(filename)
@@ -359,7 +468,7 @@ def check_content(filename, data, year=None):
     try:
         text, _ = _decode_content(filename, data)
     except (LookupError, SyntaxError, UnicodeDecodeError):
-        return 'file encoding could not be decoded'
+        return DECODE_ERROR
 
     spans, _ = _find_headers(filename, style, text.splitlines(keepends=True))
     if len(spans) > 1:
@@ -385,7 +494,7 @@ def fix_content(filename, data, year=None):
     expected = _render_header(style, newline, year)
     if not spans:
         fixed = _insert_header(filename, text, lines, classified, expected, newline)
-        return fixed.encode(encoding) if encoding else fixed
+        return _finish_fix(filename, text, fixed, encoding, newline)
 
     keep = next((span for span in spans if span.valid), spans[0])
     output = []
@@ -401,8 +510,7 @@ def fix_content(filename, data, year=None):
         elif index < len(classified) and classified[index].kind == 'blank':
             index += 1
     output.extend(lines[index:])
-    fixed = ''.join(output)
-    return fixed.encode(encoding) if encoding else fixed
+    return _finish_fix(filename, text, ''.join(output), encoding, newline)
 
 
 def process_files(files, fix=False, year=None):
@@ -415,7 +523,7 @@ def process_files(files, fix=False, year=None):
         issue = check_content(filename, data, year)
         if issue is None:
             continue
-        if fix:
+        if fix and issue != DECODE_ERROR:
             fixed = fix_content(filename, data, year)
             if isinstance(fixed, str):
                 fixed = fixed.encode('utf-8')
diff --git a/test/test_licence_headers.py b/test/test_licence_headers.py
index e4165b1..0a155df 100644
--- a/test/test_licence_headers.py
+++ b/test/test_licence_headers.py
@@ -462,3 +462,124 @@ def test_repeated_fix_never_adds_headers():
             fixed = licence_headers.fix_content('Foo.cs', fixed, 2026)
         assert fixed.count('This code is Copyright') == 1
         assert licence_headers.check_content('Foo.cs', fixed, 2026) is None
+
+
+def _drop_template_lines(header, start, count):
+    lines = header.splitlines(keepends=True)
+    return ''.join(lines[:start] + lines[start + count:])
+
+
+def test_large_missing_section_after_address_line_is_fully_replaced():
+    header = licence_headers._render_header('hash', year=2026)
+    source = '# keep this source comment\nprint("ok")\n'
+    for count in range(3, 7):
+        broken = _drop_template_lines(header, 3, count)
+        content = broken + source
+        assert licence_headers.check_content('example.py', content, 2026) is not None
+        fixed = _assert_stable('example.py', content)
+        assert fixed == header + source
+
+
+def test_large_missing_section_anywhere_in_header_is_fully_replaced():
+    header = licence_headers._render_header('slash', year=2026)
+    body_lines = len(header.splitlines()) - 1
+    for start in range(2, body_lines - 3):
+        broken = _drop_template_lines(header, start, 4)
+        content = '#region Licence\n' + broken + '#endregion\n// keep me\n' + CS_BODY
+        fixed = _assert_stable('Foo.cs', content)
+        assert fixed == '#region Licence\n' + header + '#endregion\n// keep me\n' + CS_BODY, start
+
+
+def test_section_recovery_preserves_source_comments_resembling_header_lines():
+    header = licence_headers._render_header('hash', year=2026)
+    truncated = ''.join(header.splitlines(keepends=True)[:3])
+    for source in [
+        '# notice.\nprint("ok")\n',
+        '# notice.\n# keep this source comment\nprint("ok")\n',
+        '# valid licence agreement as referred to above must contain this copyright\nprint("ok")\n',
+        '# notice.\nprint("ok")\n# exclusion or limitation is prohibited, void or unenforceable under governing\n# law.\n',
+    ]:
+        fixed = _assert_stable('example.py', truncated + source)
+        assert fixed == header + source
+
+
+def test_orphaned_licence_tail_after_header_fails_and_is_removed():
+    header = licence_headers._render_header('hash', year=2026)
+    orphan = ''.join(header.splitlines(keepends=True)[7:])
+    source = '# keep this source comment\nprint("ok")\n'
+    content = header + orphan + source
+    assert licence_headers.check_content('example.py', content, 2026) is not None
+    fixed = _assert_stable('example.py', content)
+    assert fixed == header + source
+
+
+def test_insertion_into_python_licence_region_keeps_encoding_declaration_in_place():
+    header = licence_headers._render_header('hash', year=2026)
+    for prefix in [
+        '#region Licence\n# coding: latin-1\n',
+        '# coding: latin-1\n#region Licence\n',
+        '#region Licence\n# coding: latin-1',
+    ]:
+        body = '\n#endregion\nname = "café"\n' if not prefix.endswith('\n') else '#endregion\nname = "café"\n'
+        source = (prefix + body).encode('latin-1')
+        fixed = licence_headers.fix_content('script.py', source, 2026)
+        assert isinstance(fixed, bytes)
+        text = fixed.decode('latin-1')
+        assert text.startswith(prefix.rstrip('\n') + '\n' + header)
+        assert licence_headers.check_content('script.py', fixed, 2026) is None
+        assert licence_headers.fix_content('script.py', fixed, 2026) == fixed
+        compile(fixed, 'script.py', 'exec')
+
+
+def test_header_replacement_keeps_python_encoding_declaration_effective():
+    header = licence_headers._render_header('hash', year=2026)
+    legacy = '# Copyright The Cambridge Crystallographic Data Centre (CCDC) 2021\n'
+    identity = '# This code is Copyright (C) 2020 The Cambridge Crystallographic Data Centre (CCDC)\n'
+    address = '# of 12 Union Road, Cambridge CB2 1EZ, UK and a proprietary work of CCDC. This\n'
+    declaration = '# coding: latin-1\n'
+    body = 'name = "café"\n'
+    cases = [
+        (legacy + declaration + body, declaration + header + body),
+        (legacy + declaration + '\n' + body, declaration + header + '\n' + body),
+        (identity + declaration + address + body, declaration + header + body),
+        ('#!/usr/bin/env python3\n' + declaration + legacy + body,
+         '#!/usr/bin/env python3\n' + declaration + header + body),
+        (legacy + declaration + header + body, declaration + header + body),
+        ((legacy + declaration + body).replace('\n', '\r\n'), (declaration + header + body).replace('\n', '\r\n')),
+    ]
+    for source, expected in cases:
+        fixed = licence_headers.fix_content('script.py', source.encode('latin-1'), 2026)
+        assert fixed.decode('latin-1') == expected
+        assert licence_headers.check_content('script.py', fixed, 2026) is None
+        assert licence_headers.fix_content('script.py', fixed, 2026) == fixed
+        compile(fixed, 'script.py', 'exec')
+
+
+def test_directives_with_trailing_comments_are_preamble():
+    header = licence_headers._render_header('slash', year=2026)
+    region = '#region Licence\n' + header + '#endregion\n'
+    cases = [
+        ('Foo.cs', 'using System; // imports\n' + region + CS_BODY),
+        ('Foo.cs', 'global using static System.Math;   // maths\nusing IO = System.IO; /* alias */\n' + region + CS_BODY),
+        ('app.js', "'use strict'; // strict mode\n" + header + 'const x = 1;\n'),
+        ('app.ts', '"use strict" /* strict */\n' + header + 'const x = 1;\n'),
+    ]
+    for filename, content in cases:
+        assert licence_headers.check_content(filename, content, 2026) is None
+        assert licence_headers.fix_content(filename, content, 2026) == content
+
+
+def test_using_with_trailing_code_is_not_preamble():
+    header = licence_headers._render_header('slash', year=2026)
+    content = 'using System; class A { }\n' + header
+    assert licence_headers.check_content('Foo.cs', content, 2026) is not None
+    content = 'using System; /* note */ class A { }\n' + header
+    assert licence_headers.check_content('Foo.cs', content, 2026) is not None
+
+
+def test_process_files_reports_undecodable_file_in_fix_mode(tmp_path, capsys):
+    target = tmp_path / 'broken.py'
+    target.write_bytes(b'name = "\xe9"\n')
+    assert licence_headers.process_files([str(target)], fix=True, year=2026) == 1
+    assert 'file encoding could not be decoded' in capsys.readouterr().out
+    assert target.read_bytes() == b'name = "\xe9"\n'