repolish 0.2.0__tar.gz → 0.2.2__tar.gz

{repolish-0.2.0 → repolish-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repolish
-Version: 0.2.0
+Version: 0.2.2
 Summary: Maintain consistency across repositories
 Author: hotdog-werx
 License-Expression: MIT
@@ -119,6 +119,15 @@ like `python -c "open('file','w').write('x')"`.
 - list/array of argv parts (e.g. `['prettier', '--write', '.']`) — recommended
   when you want to avoid any ambiguity about argument parsing and quoting.
 
+Platform note
+
+- On Windows the tokenization rules differ; Repolish uses Python's `shlex` to
+  split string commands into argv lists before executing them without a shell.
+  Because quoting/escaping differs between POSIX shells and Windows, prefer the
+  argv/list form in `post_process` on Windows to avoid surprises. If you must
+  provide a single string entry, keep arguments simple (no shell metacharacters)
+  or call a committed script from the argv form.
+
 Security note
 
 We intentionally avoid running commands with `shell=True` to reduce shell
@@ -264,6 +273,89 @@ Notes and tips
 - Anchors are processed before cookiecutter rendering, so template substitutions
   still work around preserved sections.
 
+## Regex anchors and capture groups
+
+Regex anchors let you specify exactly what to preserve from a local file. Two
+important behaviors to know:
+
+- Capture group preference: If your regex includes a capturing group
+  (parentheses), Repolish will prefer the first capture group (group 1) as the
+  block to insert into the template. If there are no capture groups, Repolish
+  falls back to the entire match (group 0).
+- Safeguard trimming: As a conservative safeguard Repolish trims captured blocks
+  to a contiguous region based on indentation so that incidental following
+  sections are not accidentally pulled into the template. However, the canonical
+  way to express intent is an explicit capture group — authors should prefer to
+  capture exactly what they mean.
+
+Implementation note
+
+- Repolish computes the absolute span of the selected capture (group 1 when
+  present, otherwise the full match) inside the template and trims that slice
+  using an indentation-aware heuristic before replacing it with the trimmed
+  content extracted from the local file. Also note that the
+  `## repolish-regex[...]` declaration line is removed from the template prior
+  to matching and replacement. This avoids accidentally removing unrelated
+  template sections when patterns include surrounding context.
+
+Example
+
+Template (excerpt):
+
+```toml
+cat1:
+  - line1
+  - line2
+  ## repolish-regex[cat1-filter]: (^\s*# cat1-filter-additional-paths.*\n(?:\s+.*\n)*)
+  # cat1-filter-additional-paths
+
+cat2:
+  - from-template
+  ## repolish-regex[cat2-filter]: (^\s*# cat2-filter-additional-paths.*\n(?:\s+.*\n)*)
+  # cat2-filter-additional-paths
+
+cat3:
+  - cat3-line
+  ## repolish-regex[cat3-filter]: (^\s*# cat3-filter-additional-paths.*\n(?:\s+.*\n)*)
+  # cat3-filter-additional-paths
+```
+
+Local file (excerpt):
+
+```toml
+cat1:
+  - line1
+  - line2
+  # cat1-filter-additional-paths
+  - extra
+
+cat3:
+  - cat3-line
+  # cat3-filter-additional-paths
+```
+
+Result after preprocessing:
+
+```toml
+cat1:
+  - line1
+  - line2
+  # cat1-filter-additional-paths
+  - extra
+
+cat2:
+  - from-template
+  # cat2-filter-additional-paths
+
+cat3:
+  - cat3-line
+  # cat3-filter-additional-paths
+```
+
+When your regex is too greedy, tighten it or add explicit parentheses around the
+intended capture so Repolish can reliably hydrate the template without importing
+unrelated content.
+
 ### Where anchors are declared and uniqueness
 
 Anchors can come from three places (and are merged in this order):

{repolish-0.2.0 → repolish-0.2.2}/README.md

@@ -107,6 +107,15 @@ like `python -c "open('file','w').write('x')"`.
 - list/array of argv parts (e.g. `['prettier', '--write', '.']`) — recommended
   when you want to avoid any ambiguity about argument parsing and quoting.
 
+Platform note
+
+- On Windows the tokenization rules differ; Repolish uses Python's `shlex` to
+  split string commands into argv lists before executing them without a shell.
+  Because quoting/escaping differs between POSIX shells and Windows, prefer the
+  argv/list form in `post_process` on Windows to avoid surprises. If you must
+  provide a single string entry, keep arguments simple (no shell metacharacters)
+  or call a committed script from the argv form.
+
 Security note
 
 We intentionally avoid running commands with `shell=True` to reduce shell
@@ -252,6 +261,89 @@ Notes and tips
 - Anchors are processed before cookiecutter rendering, so template substitutions
   still work around preserved sections.
 
+## Regex anchors and capture groups
+
+Regex anchors let you specify exactly what to preserve from a local file. Two
+important behaviors to know:
+
+- Capture group preference: If your regex includes a capturing group
+  (parentheses), Repolish will prefer the first capture group (group 1) as the
+  block to insert into the template. If there are no capture groups, Repolish
+  falls back to the entire match (group 0).
+- Safeguard trimming: As a conservative safeguard Repolish trims captured blocks
+  to a contiguous region based on indentation so that incidental following
+  sections are not accidentally pulled into the template. However, the canonical
+  way to express intent is an explicit capture group — authors should prefer to
+  capture exactly what they mean.
+
+Implementation note
+
+- Repolish computes the absolute span of the selected capture (group 1 when
+  present, otherwise the full match) inside the template and trims that slice
+  using an indentation-aware heuristic before replacing it with the trimmed
+  content extracted from the local file. Also note that the
+  `## repolish-regex[...]` declaration line is removed from the template prior
+  to matching and replacement. This avoids accidentally removing unrelated
+  template sections when patterns include surrounding context.
+
+Example
+
+Template (excerpt):
+
+```toml
+cat1:
+  - line1
+  - line2
+  ## repolish-regex[cat1-filter]: (^\s*# cat1-filter-additional-paths.*\n(?:\s+.*\n)*)
+  # cat1-filter-additional-paths
+
+cat2:
+  - from-template
+  ## repolish-regex[cat2-filter]: (^\s*# cat2-filter-additional-paths.*\n(?:\s+.*\n)*)
+  # cat2-filter-additional-paths
+
+cat3:
+  - cat3-line
+  ## repolish-regex[cat3-filter]: (^\s*# cat3-filter-additional-paths.*\n(?:\s+.*\n)*)
+  # cat3-filter-additional-paths
+```
+
+Local file (excerpt):
+
+```toml
+cat1:
+  - line1
+  - line2
+  # cat1-filter-additional-paths
+  - extra
+
+cat3:
+  - cat3-line
+  # cat3-filter-additional-paths
+```
+
+Result after preprocessing:
+
+```toml
+cat1:
+  - line1
+  - line2
+  # cat1-filter-additional-paths
+  - extra
+
+cat2:
+  - from-template
+  # cat2-filter-additional-paths
+
+cat3:
+  - cat3-line
+  # cat3-filter-additional-paths
+```
+
+When your regex is too greedy, tighten it or add explicit parentheses around the
+intended capture so Repolish can reliably hydrate the template without importing
+unrelated content.
+
 ### Where anchors are declared and uniqueness
 
 Anchors can come from three places (and are merged in this order):

{repolish-0.2.0 → repolish-0.2.2}/repolish/cookiecutter.py

@@ -1,6 +1,7 @@
 import difflib
 import filecmp
 import json
+import os
 import shutil
 from pathlib import Path, PurePosixPath
 
@@ -160,6 +161,57 @@ def collect_output_files(setup_output: Path) -> list[Path]:
     return [p for p in setup_output.rglob('*') if p.is_file()]
 
 
+def _preserve_line_endings() -> bool:
+    """Return True when REPOLISH_PRESERVE_LINE_ENDINGS is truthy in env.
+
+    Centralized to make behavior testable and reduce complexity in the main
+    comparison function.
+    """
+    val = os.getenv('REPOLISH_PRESERVE_LINE_ENDINGS', '')
+    return str(val).lower() in ('1', 'true', 'yes')
+
+
+def _compare_and_prepare_diff(
+    out: Path,
+    dest: Path,
+    *,
+    preserve: bool,
+) -> tuple[bool, list[str], list[str]]:
+    """Compare two files and return (same, a_lines, b_lines).
+
+    - same: True when files are equal according to the chosen policy.
+    - a_lines, b_lines: lists of lines (with line endings) to be used in a
+      unified diff when same is False. When same is True these values are
+      empty lists.
+    """
+    if preserve:
+        # fast-path equality check using filecmp (may be optimized by OS)
+        if filecmp.cmp(out, dest, shallow=False):
+            return True, [], []
+        a_raw = out.read_bytes()
+        b_raw = dest.read_bytes()
+        a_text = a_raw.decode('utf-8', errors='replace')
+        b_text = b_raw.decode('utf-8', errors='replace')
+        return (
+            False,
+            a_text.splitlines(keepends=True),
+            b_text.splitlines(keepends=True),
+        )
+
+    # Normalized comparison (ignore CRLF vs LF)
+    a_raw = out.read_bytes()
+    b_raw = dest.read_bytes()
+    a_text = a_raw.decode('utf-8', errors='replace').replace('\r\n', '\n').replace('\r', '\n')
+    b_text = b_raw.decode('utf-8', errors='replace').replace('\r\n', '\n').replace('\r', '\n')
+    if a_text == b_text:
+        return True, [], []
+    return (
+        False,
+        a_text.splitlines(keepends=True),
+        b_text.splitlines(keepends=True),
+    )
+
+
 def check_generated_output(
     setup_output: Path,
     providers: Providers,
@@ -171,27 +223,34 @@ def check_generated_output(
     """
     output_files = collect_output_files(setup_output)
     diffs: list[tuple[str, str]] = []
+
+    preserve = _preserve_line_endings()
+
     for out in output_files:
         rel = out.relative_to(setup_output / 'repolish')
         dest = base_dir / rel
         if not dest.exists():
             diffs.append((str(rel), 'MISSING'))
             continue
-        # compare contents
-        if not filecmp.cmp(out, dest, shallow=False):
-            # produce a small unified diff for logging
-            a = out.read_text(encoding='utf-8', errors='replace').splitlines()
-            b = dest.read_text(encoding='utf-8', errors='replace').splitlines()
-            ud = '\n'.join(
-                difflib.unified_diff(
-                    b,
-                    a,
-                    fromfile=str(dest),
-                    tofile=str(out),
-                    lineterm='',
-                ),
-            )
-            diffs.append((str(rel), ud))
+
+        same, a_lines, b_lines = _compare_and_prepare_diff(
+            out,
+            dest,
+            preserve=preserve,
+        )
+        if same:
+            continue
+
+        ud = ''.join(
+            difflib.unified_diff(
+                b_lines,
+                a_lines,
+                fromfile=str(dest),
+                tofile=str(out),
+                lineterm='',
+            ),
+        )
+        diffs.append((str(rel), ud))
 
     # provider-declared deletions: if a path is expected deleted but exists in
     # the project, surface that so devs know to run repolish

{repolish-0.2.0 → repolish-0.2.2}/repolish/processors.py

@@ -90,6 +90,67 @@ def replace_tags_in_content(content: str, tags: dict[str, str]) -> str:
     return content
 
 
+def _select_capture(match: re.Match) -> str:
+    """Return the author's intended capture from a regex match.
+
+    If the regex contains capturing groups, prefer the first group
+    (group 1). Otherwise fall back to the full match (group 0).
+    This lets regex authors precisely specify what should be
+    extracted and inserted.
+    """
+    if match.lastindex:
+        # prefer the first capture group when present
+        return match.group(1)
+    return match.group(0)
+
+
+def _trim_block_by_indent(block: str) -> str:
+    """Trim a matched block to the contiguous, same-indentation region.
+
+    Keeps the first line and any immediately following lines that are
+    either blank or indented at least as far as the first line. Stops at
+    the first subsequent line with smaller indentation. This heuristic is
+    intentionally simple and works well for indentation-based formats
+    (YAML, Python-ish lists, etc.) but is only a safeguard — authors
+    should prefer explicit capture groups to precisely control what to
+    extract.
+    """
+    lines = block.splitlines(keepends=True)
+    if not lines:
+        return block
+    first = lines[0]
+    anchor_indent = len(first) - len(first.lstrip(' '))
+    kept = [first]
+    for ln in lines[1:]:
+        if ln.strip() == '':
+            kept.append(ln)
+            continue
+        indent = len(ln) - len(ln.lstrip(' '))
+        if indent >= anchor_indent:
+            kept.append(ln)
+        else:
+            break
+    return ''.join(kept)
+
+
+def _extend_trimmed_region_to_include_whitespace(
+    content: str,
+    trimmed_end: int,
+    tpl_cap_end: int,
+) -> int:
+    """Preserve trailing whitespace-only content from the original capture."""
+    if trimmed_end < tpl_cap_end:
+        between = content[trimmed_end:tpl_cap_end]
+        # only extend if between contains only spaces/tabs (no other
+        # non-whitespace characters) and includes at least one newline
+        # so we don't accidentally swallow inline spaces.
+        # Consider all whitespace (including newlines) when deciding if the
+        # slice is empty of non-whitespace characters.
+        if between.strip() == '' and '\n' in between:
+            return tpl_cap_end
+    return trimmed_end
+
+
 def apply_regex_replacements(
     content: str,
     regexes: dict[str, str],
@@ -105,9 +166,59 @@ def apply_regex_replacements(
     # apply regex replacements
     for regex_pattern in regexes.values():
         pattern = re.compile(rf'{regex_pattern}', re.MULTILINE)
-        matches = pattern.search(local_file_content)
-        if matches:
-            content = pattern.sub(rf'{matches.group(0)}', content)
+        local_match = pattern.search(local_file_content)
+        if not local_match:
+            continue
+
+        # Prefer the author's explicit capture when present (group 1); if no
+        # capture is present fall back to the full match (group 0). This gives
+        # template authors precise control while remaining backwards
+        # compatible for patterns that don't use groups.
+        local_matched_raw = _select_capture(local_match)
+        local_matched = _trim_block_by_indent(local_matched_raw)
+
+        # Find where the pattern would match in the template content (after
+        # we've removed the declaration line). Trim the template match using
+        # the same indentation-aware heuristic so we only replace the
+        # anchor's block and don't remove following unrelated sections from
+        # the template.
+        template_match = pattern.search(content)
+        if not template_match:
+            # nothing to replace in template
+            continue
+
+        # Determine which group index we used (1 when the author provided a
+        # capture group, otherwise 0 for the full match). Compute the absolute
+        # span of that selected region in the template so replacements are
+        # performed at the correct indices even when the declared pattern
+        # includes surrounding context.
+        tpl_group_idx = 1 if template_match.lastindex else 0
+        tpl_cap_start, tpl_cap_end = template_match.span(tpl_group_idx)
+
+        tpl_matched_raw = content[tpl_cap_start:tpl_cap_end]
+        tpl_matched = _trim_block_by_indent(tpl_matched_raw)
+
+        # Replace only the trimmed matched region in the template with the
+        # trimmed local content. The trimmed region starts at the capture
+        # start and extends the length of the trimmed text. However, if the
+        # template contained only whitespace (spaces/newlines) between the
+        # end of the trimmed block and the original capture end (for
+        # example a blank line before the next section marker), preserve
+        # that whitespace so surrounding structure/spacing is unchanged.
+        trimmed_start = tpl_cap_start
+        trimmed_end = tpl_cap_start + len(tpl_matched)
+
+        # Potentially extend the trimmed end to include whitespace-only
+        # padding that was part of the original capture. Delegate to the
+        # helper so the logic is tested and `apply_regex_replacements` is
+        # easier to read.
+        trimmed_end = _extend_trimmed_region_to_include_whitespace(
+            content,
+            trimmed_end,
+            tpl_cap_end,
+        )
+
+        content = content[:trimmed_start] + local_matched + content[trimmed_end:]
     return content
 
 

repolish-0.2.2/repolish/version.py

@@ -0,0 +1 @@
+__version__ = '0.2.2'

repolish-0.2.0/repolish/version.py

@@ -1 +0,0 @@
-__version__ = '0.2.0'