Add -D/--decorations option with github-markdown output to show-paths

Add a new decoration mode that produces GitHub-flavored markdown with
clickable blob links to specific line numbers. Match lines are bolded
with **...** for visual distinction. Filenames are hyperlinked to the
file's blob URL. Supports both inline and full-lines formats.

Other decoration modes: 'color' (force ANSI), 'none' (plain text),
'auto' (defers to --color for backward compatibility).

Co-Authored-By: Claude Code 2.1.63 / Claude Opus 4.6 <noreply@anthropic.com>

Author: yarikoptic

bin/show-paths

@@ -84,7 +84,9 @@ Examples from my pains of the past two days
 """  # noqa: E501
 
 import argparse
+import os
 import re
+import subprocess
 import sys
 
 try:
@@ -111,6 +113,80 @@ class ColoredHelpFormatter(argparse.RawDescriptionHelpFormatter):
         return help_text
 
 
+def get_github_context():
+    """Return (repo_toplevel, commit_sha, github_blob_base) or None.
+
+    Resolves git repository info and GitHub remote URL to construct
+    blob URLs like https://github.com/owner/repo/blob/sha.
+    """
+    try:
+        toplevel = (
+            subprocess.check_output(
+                ["git", "rev-parse", "--show-toplevel"], stderr=subprocess.DEVNULL
+            )
+            .decode()
+            .strip()
+        )
+        sha = (
+            subprocess.check_output(
+                ["git", "rev-parse", "HEAD"], stderr=subprocess.DEVNULL
+            )
+            .decode()
+            .strip()
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+    # Determine remote name: tracking remote for current branch, fallback to origin
+    remote_name = "origin"
+    try:
+        ref = (
+            subprocess.check_output(
+                ["git", "symbolic-ref", "-q", "HEAD"], stderr=subprocess.DEVNULL
+            )
+            .decode()
+            .strip()
+        )
+        branch = ref.replace("refs/heads/", "")
+        remote_name = (
+            subprocess.check_output(
+                ["git", "config", f"branch.{branch}.remote"], stderr=subprocess.DEVNULL
+            )
+            .decode()
+            .strip()
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+
+    try:
+        remote_url = (
+            subprocess.check_output(
+                ["git", "config", "--get", f"remote.{remote_name}.url"],
+                stderr=subprocess.DEVNULL,
+            )
+            .decode()
+            .strip()
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+    # Parse SSH or HTTPS GitHub URLs
+    # SSH: git@github.com:owner/repo.git
+    m = re.match(r"git@github\.com[:/](.+?)(?:\.git)?$", remote_url)
+    if not m:
+        # HTTPS: https://github.com/owner/repo.git
+        m = re.match(r"https?://github\.com/(.+?)(?:\.git)?$", remote_url)
+    if not m:
+        # gh: shorthand
+        m = re.match(r"gh:(.+?)(?:\.git)?$", remote_url)
+    if not m:
+        return None
+
+    owner_repo = m.group(1)
+    blob_base = f"https://github.com/{owner_repo}/blob/{sha}"
+    return toplevel, sha, blob_base
+
+
 def get_paths(lines):
     """Generate indentation-based paths for given lines."""
     paths = []
@@ -162,6 +238,51 @@ def print_full_lines(paths, lines, use_color, prefix=""):
         printed.add(line_num)
 
 
+def print_inline_markdown(paths, lines, blob_url, use_color, prefix=""):
+    """Print paths and matched lines in inline format with GitHub markdown links."""
+    for line_num, path in paths:
+        path_str = ".".join([p[0] for p in path[:-1]])
+        line = lines[line_num].rstrip()
+        # GitHub uses 1-indexed line numbers
+        gh_line = line_num + 1
+        path_part = f" `{path_str}`" if path_str else ""
+        if blob_url:
+            text = f"**[`{line_num}:`]({blob_url}#L{gh_line}){path_part} `{line}`**"
+        else:
+            text = f"**`{line_num}:`{path_part} `{line}`**"
+        if use_color:
+            text = colored(text, "red")
+        print(f"{prefix}{text}")
+
+
+def print_full_lines_markdown(paths, lines, blob_url, use_color, prefix=""):
+    """Print paths and matched lines in full-lines format with GitHub markdown links."""
+    printed = set()
+    for line_num, path in paths:
+        for key, indent, i in path[:-1]:
+            if i not in printed:
+                gh_i = i + 1
+                context_line = lines[i]
+                if blob_url:
+                    text = f"[`{i} `]({blob_url}#L{gh_i}) `{context_line}`"
+                else:
+                    text = f"`{i} ` `{context_line}`"
+                if use_color:
+                    text = colored(text, attrs=["dark"])
+                print(f"{prefix}{text}")
+                printed.add(i)
+        gh_line = line_num + 1
+        match_line = lines[line_num]
+        if blob_url:
+            text = f"**[`{line_num}:`]({blob_url}#L{gh_line}) `{match_line}`**"
+        else:
+            text = f"**`{line_num}:` `{match_line}`**"
+        if use_color:
+            text = colored(text, "red")
+        print(f"{prefix}{text}")
+        printed.add(line_num)
+
+
 def filter_paths(lines, regex=None, line_numbers=None):
     """Get and filter indentation-based paths for given lines."""
     paths = get_paths(lines)
@@ -175,9 +296,7 @@ def filter_paths(lines, regex=None, line_numbers=None):
 
     if line_numbers:
         nums = set(line_numbers)
-        paths = [
-            (line_num, path) for line_num, path in paths if line_num in nums
-        ]
+        paths = [(line_num, path) for line_num, path in paths if line_num in nums]
 
     return paths
 
@@ -221,16 +340,50 @@ def main():
         help="How to annotate output with filename: 'auto' (prefix when multiple files),"
         " 'prefix' (prepend filename: to each line), 'name' (print filename header)",
     )
+    parser.add_argument(
+        "-D",
+        "--decorations",
+        choices=["auto", "color", "none", "github-markdown"],
+        default="auto",
+        help="Decoration style: 'auto' (defers to --color), 'color' (force ANSI),"
+        " 'none' (plain text), 'github-markdown' (markdown with GitHub blob links)",
+    )
 
     args = parser.parse_args()
 
+    decorations = args.decorations
+
     # Determine if color output should be used
-    use_color = args.color == "on" or (
-        args.color == "auto" and sys.stdout.isatty() and colored
-    )
+    if decorations == "auto":
+        # Defer to --color logic (backward compatible)
+        use_color = args.color == "on" or (
+            args.color == "auto" and sys.stdout.isatty() and colored
+        )
+    elif decorations == "color":
+        use_color = True
+    elif decorations == "none":
+        use_color = False
+    elif decorations == "github-markdown":
+        # Colors on top of markdown when TTY
+        use_color = sys.stdout.isatty() and colored is not None
+    else:
+        use_color = False
+
     if use_color and not colored:
         raise RuntimeError("Need 'termcolor' package to get colors")
 
+    # Resolve GitHub context if needed
+    github_context = None
+    if decorations == "github-markdown":
+        github_context = get_github_context()
+        if github_context is None:
+            print(
+                "Error: --decorations=github-markdown requires a git repo"
+                " with a GitHub remote",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
     # Compile regex if provided
     regex = re.compile(args.regex) if args.regex else None
 
@@ -257,17 +410,49 @@ def main():
         if not paths:
             continue
 
-        prefix = f"{fname}:" if filename_mode == "prefix" else ""
-
-        if filename_mode == "name":
-            print(fname)
-
-        if args.format == "inline":
-            print_inline(paths, lines, use_color, prefix=prefix)
-        elif args.format == "full-lines":
-            print_full_lines(paths, lines, use_color, prefix=prefix)
+        if decorations == "github-markdown":
+            # Compute blob URL for this file
+            if filepath is not None and github_context is not None:
+                toplevel, _sha, blob_base = github_context
+                rel_path = os.path.relpath(os.path.abspath(filepath), toplevel)
+                blob_url = f"{blob_base}/{rel_path}"
+            else:
+                blob_url = None
+
+            # Build markdown prefix/header with hyperlinked filename
+            if filename_mode == "prefix":
+                if blob_url:
+                    prefix = f"[`{fname}`]({blob_url}):"
+                else:
+                    prefix = f"`{fname}`:"
+            else:
+                prefix = ""
+
+            if filename_mode == "name":
+                if blob_url:
+                    print(f"[`{fname}`]({blob_url})")
+                else:
+                    print(f"`{fname}`")
+
+            if args.format == "inline":
+                print_inline_markdown(paths, lines, blob_url, use_color, prefix=prefix)
+            elif args.format == "full-lines":
+                print_full_lines_markdown(
+                    paths, lines, blob_url, use_color, prefix=prefix
+                )
+            else:
+                raise ValueError(args.format)
         else:
-            raise ValueError(args.format)
+            prefix = f"{fname}:" if filename_mode == "prefix" else ""
+
+            if filename_mode == "name":
+                print(fname)
+            if args.format == "inline":
+                print_inline(paths, lines, use_color, prefix=prefix)
+            elif args.format == "full-lines":
+                print_full_lines(paths, lines, use_color, prefix=prefix)
+            else:
+                raise ValueError(args.format)
 
 
 if __name__ == "__main__":