codeannex 0.1.1__tar.gz

codeannex-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanhleno Teixeira de Sousa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codeannex-0.1.1/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: codeannex
+Version: 0.1.1
+Summary: Generates a professional PDF source code annex with Smart Index, Images and Emoji support.
+License: MIT
+Project-URL: Repository, https://github.com/tanhleno/codeannex
+Keywords: pdf,source-code,documentation,annex,reportlab,emoji
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: reportlab>=4.0
+Requires-Dist: Pillow>=10.0
+Requires-Dist: Pygments>=2.16
+Requires-Dist: pdfminer.six>=20231228
+Provides-Extra: svg
+Requires-Dist: cairosvg>=2.7; extra == "svg"
+Requires-Dist: svglib>=1.5; extra == "svg"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# 📂 codeannex
+
+Generates a professional PDF annex from a project's source code — with syntax highlighting, a clickable table of contents, image rendering, non-selectable line numbers, and configurable fonts.
+
+## Features
+
+- **Syntax highlighting** via Pygments (Catppuccin Mocha theme)
+- **Clickable table of contents** with page numbers (two-pass layout)
+- **Smart word wrap** — breaks at word boundaries, respects emoji codepoints
+- **Non-selectable line numbers** rendered as images
+- **Image support** — embeds PNG, JPG, GIF, WebP, BMP, ICO, and SVG files
+- **Git-aware** — uses `git ls-files` when available; falls back to manual `.gitignore` parsing
+- **Cross-platform font discovery** — finds monospace and emoji fonts on Windows, macOS, and Linux
+- **Emoji support** — configurable fonts for emojis, with fallback for better rendering.
+  - *Tip for Linux:* Install `fonts-symbola` for high-coverage monochromatic emoji support that works reliably with ReportLab.
+- **Emoji descriptions** — option to print `[EMOJI NAME]` instead of glyphs for systems without emoji fonts.
+- **Configurable fonts** — customize normal, bold, monospace, and emoji fonts.
+- **Page numbering** — customizable font size and position.
+- **Repository Link** — show a clickable repository link on the cover page.
+- **Fast binary file detection** — quickly ignores common binary extensions.
+
+## Requirements
+
+- Python >= 3.11
+- `reportlab`, `Pillow`, `Pygments`
+
+Optional SVG rendering (install at least one):
+- `cairosvg` (preferred)
+- `svglib`
+
+For development and testing:
+- `pytest` (install with `pip install -e ".[dev]"`)
+
+## Installation
+
+```bash
+pip install codeannex
+```
+
+With SVG support:
+
+```bash
+pip install "codeannex[svg]"
+```
+## Requirements
+
+- Python >= 3.11
+- `reportlab`, `Pillow`, `Pygments`, `pdfminer.six`
+
+Optional SVG rendering (install at least one):
+...
+## Usage
+
+```bash
+# Annotate current directory
+codeannex
+
+# Annotate a specific project
+codeannex /path/to/project
+
+# Custom output filename
+codeannex /path/to/project -o my_annex.pdf
+
+# Customized configuration (margins in cm)
+codeannex /path/to/project \
+  --name "My Project" \
+  --repo-url "https://github.com/user/repo" \
+  --margin 1.5 \
+  --margin-top 2.5 \
+  --page-number-size 10 \
+  --show-project
+```
+
+### Configuration Options
+
+- `--name NAME` — Custom project name (default: directory name).
+- `--repo-url URL` — Repository URL to show as a clickable link on the cover.
+- `--start-page N` — Starting page number (default: 1).
+- `--margin CM` — General margin in cm for all sides.
+- `--margin-left CM` — Left margin in cm (default: 1.5).
+- `--margin-right CM` — Right margin in cm (default: 1.5).
+- `--margin-top CM` — Top margin in cm (default: 2.0).
+- `--margin-bottom CM` — Bottom margin in cm (default: 2.0).
+- `--show-project` — Show project name in page footer (default: off).
+- `--page-number-size N` — Font size for page numbers (default: 8).
+- `--normal-font FONT` — Font for normal text (default: Helvetica).
+- `--bold-font FONT` — Font for bold text (default: Helvetica-Bold).
+- `--mono-font FONT` — Monospace font for code (default: auto-detect).
+- `--emoji-font FONT` — Font for emojis (default: auto-detect).
+- `--emoji-description` — Print `[DESCRIPTION]` instead of emoji glyphs.
+- `--check-emoji-font` — Check current emoji font style and exit.
+
+
+## Testing
+
+Run the test suite with pytest:
+
+```bash
+pytest
+```
+
+## Output
+
+The generated PDF contains:
+
+1. **Cover page** — project name with page number
+2. **Table of contents** — tree-structured, with clickable links to each file
+3. **File pages** — syntax-highlighted source, with file path headers and line numbers
+
+Files are ordered: root files first (alphabetical), then directories recursively (alphabetical).
+
+Binary files (e.g., .pdf, .exe) are automatically ignored with warnings if not in .gitignore.
+
+## License
+
+MIT

codeannex-0.1.1/README.md

@@ -0,0 +1,116 @@
+# 📂 codeannex
+
+Generates a professional PDF annex from a project's source code — with syntax highlighting, a clickable table of contents, image rendering, non-selectable line numbers, and configurable fonts.
+
+## Features
+
+- **Syntax highlighting** via Pygments (Catppuccin Mocha theme)
+- **Clickable table of contents** with page numbers (two-pass layout)
+- **Smart word wrap** — breaks at word boundaries, respects emoji codepoints
+- **Non-selectable line numbers** rendered as images
+- **Image support** — embeds PNG, JPG, GIF, WebP, BMP, ICO, and SVG files
+- **Git-aware** — uses `git ls-files` when available; falls back to manual `.gitignore` parsing
+- **Cross-platform font discovery** — finds monospace and emoji fonts on Windows, macOS, and Linux
+- **Emoji support** — configurable fonts for emojis, with fallback for better rendering.
+  - *Tip for Linux:* Install `fonts-symbola` for high-coverage monochromatic emoji support that works reliably with ReportLab.
+- **Emoji descriptions** — option to print `[EMOJI NAME]` instead of glyphs for systems without emoji fonts.
+- **Configurable fonts** — customize normal, bold, monospace, and emoji fonts.
+- **Page numbering** — customizable font size and position.
+- **Repository Link** — show a clickable repository link on the cover page.
+- **Fast binary file detection** — quickly ignores common binary extensions.
+
+## Requirements
+
+- Python >= 3.11
+- `reportlab`, `Pillow`, `Pygments`
+
+Optional SVG rendering (install at least one):
+- `cairosvg` (preferred)
+- `svglib`
+
+For development and testing:
+- `pytest` (install with `pip install -e ".[dev]"`)
+
+## Installation
+
+```bash
+pip install codeannex
+```
+
+With SVG support:
+
+```bash
+pip install "codeannex[svg]"
+```
+## Requirements
+
+- Python >= 3.11
+- `reportlab`, `Pillow`, `Pygments`, `pdfminer.six`
+
+Optional SVG rendering (install at least one):
+...
+## Usage
+
+```bash
+# Annotate current directory
+codeannex
+
+# Annotate a specific project
+codeannex /path/to/project
+
+# Custom output filename
+codeannex /path/to/project -o my_annex.pdf
+
+# Customized configuration (margins in cm)
+codeannex /path/to/project \
+  --name "My Project" \
+  --repo-url "https://github.com/user/repo" \
+  --margin 1.5 \
+  --margin-top 2.5 \
+  --page-number-size 10 \
+  --show-project
+```
+
+### Configuration Options
+
+- `--name NAME` — Custom project name (default: directory name).
+- `--repo-url URL` — Repository URL to show as a clickable link on the cover.
+- `--start-page N` — Starting page number (default: 1).
+- `--margin CM` — General margin in cm for all sides.
+- `--margin-left CM` — Left margin in cm (default: 1.5).
+- `--margin-right CM` — Right margin in cm (default: 1.5).
+- `--margin-top CM` — Top margin in cm (default: 2.0).
+- `--margin-bottom CM` — Bottom margin in cm (default: 2.0).
+- `--show-project` — Show project name in page footer (default: off).
+- `--page-number-size N` — Font size for page numbers (default: 8).
+- `--normal-font FONT` — Font for normal text (default: Helvetica).
+- `--bold-font FONT` — Font for bold text (default: Helvetica-Bold).
+- `--mono-font FONT` — Monospace font for code (default: auto-detect).
+- `--emoji-font FONT` — Font for emojis (default: auto-detect).
+- `--emoji-description` — Print `[DESCRIPTION]` instead of emoji glyphs.
+- `--check-emoji-font` — Check current emoji font style and exit.
+
+
+## Testing
+
+Run the test suite with pytest:
+
+```bash
+pytest
+```
+
+## Output
+
+The generated PDF contains:
+
+1. **Cover page** — project name with page number
+2. **Table of contents** — tree-structured, with clickable links to each file
+3. **File pages** — syntax-highlighted source, with file path headers and line numbers
+
+Files are ordered: root files first (alphabetical), then directories recursively (alphabetical).
+
+Binary files (e.g., .pdf, .exe) are automatically ignored with warnings if not in .gitignore.
+
+## License
+
+MIT

codeannex-0.1.1/codeannex/__main__.py

@@ -0,0 +1,157 @@
+import argparse
+import io
+import os
+from pathlib import Path
+
+from .config import IMAGE_EXTENSIONS, BINARY_EXTENSIONS, PDFConfig
+from .file_utils import get_project_files, classify_file, sort_files
+from .fonts import init_sprites, register_best_font, register_emoji_font
+from .pdf_builder import ModernAnnexPDF
+from reportlab.lib.units import cm
+
+
+def check_emoji_font_style():
+    """Utility function to check current emoji font style."""
+    from .fonts import register_emoji_font, get_emoji_font_style, is_google_like_emoji_font
+
+    emoji_font = register_emoji_font()
+    if emoji_font:
+        # Tentar obter informações sobre a fonte
+        # Nota: Esta é uma simplificação - em produção teríamos o caminho armazenado
+        print(f"✅ Emoji font registered: {emoji_font}")
+        print("ℹ️  To check if using Google-like style, look for 'Noto' in the font path above")
+        print("💡 Tip: Install Google Noto fonts for authentic Google emoji style")
+    else:
+        print("⚠️  No emoji font found - emojis may not render correctly")
+    return emoji_font
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generates a PDF code annex with Smart Index and Images.")
+    parser.add_argument("dir", nargs="?", default=".", help="Project directory")
+    parser.add_argument("-o", "--output", default=None, help="Output PDF filename")
+    parser.add_argument("-n", "--name", default=None, help="Project name (default: directory name)")
+    parser.add_argument("--margin", type=float, default=None, help="General margin in cm for all sides")
+    parser.add_argument("--margin-left", type=float, default=None, help="Left margin in cm (default: 1.5cm)")
+    parser.add_argument("--margin-right", type=float, default=None, help="Right margin in cm (default: 1.5cm)")
+    parser.add_argument("--margin-top", type=float, default=None, help="Top margin in cm (default: 2.0cm)")
+    parser.add_argument("--margin-bottom", type=float, default=None, help="Bottom margin in cm (default: 2.0cm)")
+    parser.add_argument("--start-page", type=int, default=1, help="Starting page number (default: 1)")
+    parser.add_argument("--show-project", action="store_true", help="Show project name in footer")
+    parser.add_argument("--repo-url", default=None, help="Repository URL to show on cover")
+    parser.add_argument("--page-number-size", type=int, default=8, help="Font size for page numbers (default: 8)")
+    parser.add_argument("--normal-font", default=None, help="Normal text font (default: Helvetica)")
+    parser.add_argument("--bold-font", default=None, help="Bold text font (default: Helvetica-Bold)")
+    parser.add_argument("--mono-font", default=None, help="Monospace font for code (default: auto-detect)")
+    parser.add_argument("--emoji-font", default=None, help="Font for emojis (default: auto-detect)")
+    parser.add_argument("--emoji-description", action="store_true", help="Print [description] instead of emoji glyphs")
+    parser.add_argument("--check-emoji-font", action="store_true", help="Check current emoji font style and exit")
+
+    args, unknown = parser.parse_known_args()
+
+    # Handle unknown arguments
+    if unknown:
+        for u in unknown:
+            if u.startswith("-"):
+                print(f"⚠️  Warning: Unrecognized argument ignored: {u}")
+
+    # Handle emoji font check
+    if args.check_emoji_font:
+        check_emoji_font_style()
+        return
+
+    root   = Path(args.dir).resolve()
+    output = args.output or f"{root.name}_anexo_codigo.pdf"
+
+    script_path = Path(os.path.abspath(__file__))
+    output_path = Path(output).resolve()
+
+    mono_font, is_ttf, ttf_path = register_best_font()
+    # If --emoji-description is NOT set, we MUST have an emoji font or we exit with error
+    emoji_font = register_emoji_font(error_on_missing=not args.emoji_description)
+    init_sprites(is_ttf, ttf_path)
+
+    # Determine margin values (specific margins override general --margin)
+    def get_margin(spec, general, default):
+        if spec is not None:
+            return spec * cm
+        if general is not None:
+            return general * cm
+        return default
+
+    # Criar configuração
+    config = PDFConfig(
+        project_name=args.name or root.name,
+        margin_left=get_margin(args.margin_left, args.margin, PDFConfig().margin_left),
+        margin_right=get_margin(args.margin_right, args.margin, PDFConfig().margin_right),
+        margin_top=get_margin(args.margin_top, args.margin, PDFConfig().margin_top),
+        margin_bottom=get_margin(args.margin_bottom, args.margin, PDFConfig().margin_bottom),
+        start_page_num=args.start_page,
+        show_project_name=args.show_project,
+        normal_font=args.normal_font or PDFConfig().normal_font,
+        bold_font=args.bold_font or PDFConfig().bold_font,
+        mono_font=args.mono_font or mono_font,
+        emoji_font=args.emoji_font or emoji_font,
+        emoji_description=args.emoji_description,
+        repo_url=args.repo_url,
+        page_number_size=args.page_number_size,
+    )
+
+    print(f"🔍 Analyzing directory: {root}")
+    all_files = sort_files(get_project_files(root), root)
+    included  = []
+    ignored_binaries = []
+
+    for fp in all_files:
+        try:
+            if fp.resolve() in (script_path, output_path):
+                continue
+        except Exception:
+            pass
+        if not fp.is_file():
+            continue
+
+        ext = fp.suffix.lower()
+
+        # Check known extensions first (without reading file)
+        if ext == ".svg":
+            included += [(fp, "image"), (fp, "text")]
+            continue
+        elif ext in IMAGE_EXTENSIONS:
+            included.append((fp, "image"))
+            continue
+        elif ext in BINARY_EXTENSIONS:
+            ignored_binaries.append(fp)
+            continue
+
+        # Classify file with a single read
+        file_type = classify_file(fp)
+        if file_type == "text":
+            included.append((fp, "text"))
+        elif file_type == "binary":
+            ignored_binaries.append(fp)
+
+    if ignored_binaries:
+        for bp in ignored_binaries:
+            rel_path = bp.relative_to(root)
+            print(f"⚠️ Ignoring binary file: {rel_path}")
+
+    if not included:
+        print("❌ No compatible files found.")
+        return
+
+    print(f"🧮 Step 1/2: Simulating layout of {len(included)} files to generate the Table of Contents...")
+    pdf_sim = ModernAnnexPDF(io.BytesIO(), root, mono_font, emoji_font, config)
+    pdf_sim.is_simulation = True
+    pdf_sim.build(included)
+
+    print("🚀 Step 2/2: Generating the final document with images and code...")
+    pdf_final = ModernAnnexPDF(output, root, mono_font, emoji_font, config)
+    pdf_final.summary_data = pdf_sim.summary_data
+    pdf_final.build(included)
+
+    print(f"✅ Success! The annex was saved to: {output}")
+
+
+if __name__ == "__main__":
+    main()

codeannex-0.1.1/codeannex/config.py

@@ -0,0 +1,65 @@
+from dataclasses import dataclass
+from reportlab.lib import colors
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.units import mm, cm
+
+# ── Page (default) ───────────────────────────────
+PAGE_W, PAGE_H = A4
+_DEFAULT_MARGIN_LEFT    = 1.5 * cm
+_DEFAULT_MARGIN_RIGHT   = 1.5 * cm
+_DEFAULT_MARGIN_TOP     = 2.0 * cm
+_DEFAULT_MARGIN_BOTTOM  = 2.0 * cm
+
+# ── Code ───────────────────────────────────────
+CODE_FONT_SIZE = 10
+CODE_LINE_H    = CODE_FONT_SIZE * 1.4
+GUTTER_W       = 14 * mm
+
+# ── Colors ────────────────────────────────────────
+COLOR_PAGE_BG   = colors.HexColor("#ffffff")
+COLOR_TEXT_MAIN = colors.HexColor("#4c4f69")
+COLOR_CODE_BG   = colors.HexColor("#1e1e2e")
+COLOR_GUTTER_BG = colors.HexColor("#181825")
+COLOR_GUTTER_FG = colors.HexColor("#bac2de")
+COLOR_HEADER_BG = colors.HexColor("#313244")
+COLOR_HEADER_FG = colors.HexColor("#cdd6f4")
+COLOR_ACCENT    = colors.HexColor("#89b4fa")
+
+# ── Base fonts ──────────────────────────────────
+NORMAL_FONT = "Helvetica"
+BOLD_FONT   = "Helvetica-Bold"
+
+# ── Supported image extensions ───────────────
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".ico", ".gif", ".webp", ".bmp", ".svg"}
+
+# ── Binary extensions to ignore quickly ──────
+BINARY_EXTENSIONS = {".pdf", ".pyc", ".pyo", ".exe", ".dll", ".so", ".dylib",
+                     ".zip", ".tar", ".gz", ".rar", ".7z", ".jar", ".whl",
+                     ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx"}
+
+
+@dataclass
+class PDFConfig:
+    """PDF configuration for code annex."""
+    project_name: str | None = None
+    margin_left: float = _DEFAULT_MARGIN_LEFT
+    margin_right: float = _DEFAULT_MARGIN_RIGHT
+    margin_top: float = _DEFAULT_MARGIN_TOP
+    margin_bottom: float = _DEFAULT_MARGIN_BOTTOM
+    start_page_num: int = 1
+    show_project_name: bool = False
+    normal_font: str = NORMAL_FONT
+    bold_font: str = BOLD_FONT
+    mono_font: str | None = None  # Will be set by register_best_font
+    emoji_font: str | None = None  # Will be set by register_emoji_font
+    emoji_description: bool = False  # Print descriptions instead of emojis
+    repo_url: str | None = None  # URL of the repository for the cover page
+    page_number_size: int = 8  # Font size for page numbers
+
+    def get_code_x(self) -> float:
+        """Calculates the initial X position of the code."""
+        return self.margin_left + GUTTER_W
+
+    def get_code_w(self) -> float:
+        """Calculates the available width for code."""
+        return PAGE_W - self.get_code_x() - self.margin_right

codeannex-0.1.1/codeannex/file_utils.py

@@ -0,0 +1,116 @@
+import fnmatch
+import os
+import subprocess
+from pathlib import Path
+
+
+def classify_file(filepath: Path) -> str:
+    """
+    Detects binaries cross-platform (Windows/Linux/macOS).
+    Simple and reliable heuristic: null bytes = binary
+    Returns: "text", "binary", or "error"
+    """
+    try:
+        # Empty files are text
+        if filepath.stat().st_size == 0:
+            return "text"
+
+        # Read first 512 bytes (enough to detect null bytes)
+        with open(filepath, "rb") as f:
+            chunk = f.read(512)
+
+        # Null bytes is the most reliable indicator of binary
+        # (works on Windows, Linux, macOS without dependencies)
+        if b"\0" in chunk:
+            return "binary"
+
+        return "text"
+    except Exception:
+        return "error"
+
+
+def is_text_file(filepath: Path) -> bool:
+    # Rejeita extensões binárias conhecidas rapidamente
+    binary_extensions = {".pdf", ".pyc", ".pyo", ".exe", ".dll", ".so", ".dylib",
+                        ".zip", ".tar", ".gz", ".rar", ".7z", ".jar", ".whl"}
+    if filepath.suffix.lower() in binary_extensions:
+        return False
+
+    return classify_file(filepath) == "text"
+
+
+def is_binary_file(filepath: Path) -> bool:
+    return classify_file(filepath) == "binary"
+
+
+class FallbackGitignoreFilter:
+    def __init__(self, root: Path):
+        self.root = root
+        gi = root / ".gitignore"
+        self.rules = []
+        if gi.exists():
+            for line in gi.read_text(encoding="utf-8", errors="replace").splitlines():
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    self.rules.append(line.rstrip("/"))
+
+    def is_ignored(self, path: Path) -> bool:
+        try:
+            rel = path.relative_to(self.root)
+        except ValueError:
+            return False
+        rel_str = rel.as_posix()
+        parts   = rel.parts
+        for rule in self.rules:
+            if rule.startswith("/"):
+                r = rule[1:]
+                if fnmatch.fnmatch(rel_str, r) or fnmatch.fnmatch(rel_str, f"{r}/*"):
+                    return True
+            else:
+                if fnmatch.fnmatch(rel_str, rule) or fnmatch.fnmatch(rel_str, f"{rule}/*"):
+                    return True
+                if any(fnmatch.fnmatch(p, rule) for p in parts):
+                    return True
+        return False
+
+
+def sort_files(files: list[Path], root: Path) -> list[Path]:
+    """
+    Sorts files respecting the rule:
+    - Root files first, in alphabetical order
+    - Then each directory (alphabetical), recursively with the same rule
+    """
+    def sort_key(p: Path):
+        parts = p.relative_to(root).parts
+        # Intercala cada parte com um flag (1 = está dentro de dir, 0 = é arquivo na raiz do nível)
+        # Para cada nível exceto o último (nome do arquivo), coloca (1, nome_dir)
+        # Para o arquivo em si, coloca (0, nome) no seu nível
+        dirs  = parts[:-1]
+        fname = parts[-1]
+        return tuple(val for d in dirs for val in (1, d.lower())) + (0, fname.lower())
+
+    return sorted(files, key=sort_key)
+
+
+def get_project_files(root: Path) -> list[Path]:
+    try:
+        subprocess.run(["git", "rev-parse", "--is-inside-work-tree"],
+                       cwd=root, capture_output=True, check=True)
+        tracked   = subprocess.run(["git", "ls-files", "-z"],
+                                   cwd=root, capture_output=True, check=True).stdout.split(b"\0")
+        untracked = subprocess.run(["git", "ls-files", "-z", "--others", "--exclude-standard"],
+                                   cwd=root, capture_output=True, check=True).stdout.split(b"\0")
+        files = [root / f.decode() for f in set(tracked + untracked) if f]
+        print("✅ Using Git's native engine to perfectly interpret .gitignore.")
+        return sorted(files)
+
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        print("⚠️ Git not detected in the project. Using manual scan with Fallback.")
+        system_ignores = {".git", "node_modules", "__pycache__", "venv", ".venv", "dist", "build"}
+        filt  = FallbackGitignoreFilter(root)
+        files = []
+        for dp, dns, fns in os.walk(root):
+            curr   = Path(dp)
+            dns[:] = [d for d in dns if d not in system_ignores and not filt.is_ignored(curr / d)]
+            files.extend(curr / f for f in fns if not filt.is_ignored(curr / f))
+        return sorted(files)