reposnap 0.2.0__tar.gz

reposnap-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+# python generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# venv
+.venv
+.idea
+output.md

reposnap-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12.4

reposnap-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 agoloborodko
+
+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.

reposnap-0.2.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.3
+Name: reposnap
+Version: 0.2.0
+Summary: Generate a Markdown file with all contents of your project
+Author: agoloborodko
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: gitpython>=3.1.43
+Requires-Dist: pathlib>=1.0.1
+Requires-Dist: pathspec>=0.12.1
+Description-Content-Type: text/markdown
+
+# RepoSnap
+
+## Overview
+
+`reposnap` is a Python script designed to generate a Markdown file that documents the structure and contents of a git project. This tool is particularly useful for creating a quick overview of a project's file hierarchy, including optional syntax-highlighted code snippets.
+
+## Features
+
+- **Recursive Directory Traversal**: Automatically traverses through all subdirectories of the specified project root.
+- **File Exclusion**: Supports excluding specific files and directories using patterns similar to `.gitignore`.
+- **Syntax Highlighting**: Includes syntax highlighting for known file types in the generated Markdown file.
+- **Structure Only Option**: The `--structure-only` flag can be used to generate the Markdown file with just the directory structure, omitting the contents of the files.
+
+## Usage
+
+### Command-Line Interface
+
+To use the `collect.py` script, run it with the following options:
+
+```bash
+python -m collect <project_root> [-o OUTPUT] [-e EXCLUDE ...] [-x EXCLUDE_FILE] [--structure-only]
+```
+
+- `<project_root>`: The root directory of the project to document.
+- `-o, --output`: The name of the output Markdown file. Defaults to `repo-content-<timestamp>.md`.
+- `-e, --exclude`: Patterns of files or directories to exclude (supports multiple patterns).
+- `-x, --exclude-file`: A file (e.g., `.gitignore`) containing patterns of files or directories to exclude.
+- `--structure-only`: Generate a Markdown file that includes only the project structure, without file contents.
+
+### Examples
+
+1. **Generate a full project structure with file contents**:
+
+    ```bash
+    python -m collect my_project/
+    ```
+
+2. **Generate a project structure only**:
+
+    ```bash
+    python -m collect my_project/ --structure-only
+    ```
+
+3. **Generate a Markdown file excluding certain files and directories**:
+
+    ```bash
+    python -m collect my_project/ -e '*.log' -e 'build/' -o output.md
+    ```
+
+4. **Use exclusion patterns from a `.gitignore` file**:
+
+    ```bash
+    python -m collect my_project/ -x .gitignore
+    ```
+
+## Testing
+
+This project includes unit tests to ensure the correctness of the code:
+
+- **`test_collect.py`**: Tests the `file_extension_to_language` function, verifying that file extensions are correctly mapped to programming languages for syntax highlighting in the Markdown file.
+- **`test_cli.py`**: Tests the command-line interface of the `collect.py` script, including the `--structure-only` flag.
+
+### Running the Tests
+
+To run the tests, use `rye`:
+
+```bash
+rye test
+```
+
+This will execute all test cases and provide a summary of the results.
+
+## Dependencies
+
+This project uses standard Python libraries and does not require any external dependencies. 
+
+## License
+
+This project is licensed under the MIT License.

reposnap-0.2.0/README.md

@@ -0,0 +1,79 @@
+# RepoSnap
+
+## Overview
+
+`reposnap` is a Python script designed to generate a Markdown file that documents the structure and contents of a git project. This tool is particularly useful for creating a quick overview of a project's file hierarchy, including optional syntax-highlighted code snippets.
+
+## Features
+
+- **Recursive Directory Traversal**: Automatically traverses through all subdirectories of the specified project root.
+- **File Exclusion**: Supports excluding specific files and directories using patterns similar to `.gitignore`.
+- **Syntax Highlighting**: Includes syntax highlighting for known file types in the generated Markdown file.
+- **Structure Only Option**: The `--structure-only` flag can be used to generate the Markdown file with just the directory structure, omitting the contents of the files.
+
+## Usage
+
+### Command-Line Interface
+
+To use the `collect.py` script, run it with the following options:
+
+```bash
+python -m collect <project_root> [-o OUTPUT] [-e EXCLUDE ...] [-x EXCLUDE_FILE] [--structure-only]
+```
+
+- `<project_root>`: The root directory of the project to document.
+- `-o, --output`: The name of the output Markdown file. Defaults to `repo-content-<timestamp>.md`.
+- `-e, --exclude`: Patterns of files or directories to exclude (supports multiple patterns).
+- `-x, --exclude-file`: A file (e.g., `.gitignore`) containing patterns of files or directories to exclude.
+- `--structure-only`: Generate a Markdown file that includes only the project structure, without file contents.
+
+### Examples
+
+1. **Generate a full project structure with file contents**:
+
+    ```bash
+    python -m collect my_project/
+    ```
+
+2. **Generate a project structure only**:
+
+    ```bash
+    python -m collect my_project/ --structure-only
+    ```
+
+3. **Generate a Markdown file excluding certain files and directories**:
+
+    ```bash
+    python -m collect my_project/ -e '*.log' -e 'build/' -o output.md
+    ```
+
+4. **Use exclusion patterns from a `.gitignore` file**:
+
+    ```bash
+    python -m collect my_project/ -x .gitignore
+    ```
+
+## Testing
+
+This project includes unit tests to ensure the correctness of the code:
+
+- **`test_collect.py`**: Tests the `file_extension_to_language` function, verifying that file extensions are correctly mapped to programming languages for syntax highlighting in the Markdown file.
+- **`test_cli.py`**: Tests the command-line interface of the `collect.py` script, including the `--structure-only` flag.
+
+### Running the Tests
+
+To run the tests, use `rye`:
+
+```bash
+rye test
+```
+
+This will execute all test cases and provide a summary of the results.
+
+## Dependencies
+
+This project uses standard Python libraries and does not require any external dependencies. 
+
+## License
+
+This project is licensed under the MIT License.

reposnap-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "reposnap"
+version = "0.2.0"
+description = "Generate a Markdown file with all contents of your project"
+authors = [
+    { name = "agoloborodko" }
+]
+dependencies = [
+    "pathlib>=1.0.1",
+    "pathspec>=0.12.1",
+    "gitpython>=3.1.43",
+]
+readme = "README.md"
+requires-python = ">= 3.8"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.rye]
+managed = true
+dev-dependencies = [
+    "pytest>=8.3.2",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reposnap"]

reposnap-0.2.0/requirements-dev.lock

@@ -0,0 +1,29 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+#   generate-hashes: false
+#   universal: false
+
+-e file:.
+gitdb==4.0.11
+    # via gitpython
+gitpython==3.1.43
+    # via reposnap
+iniconfig==2.0.0
+    # via pytest
+packaging==24.1
+    # via pytest
+pathlib==1.0.1
+    # via reposnap
+pathspec==0.12.1
+    # via reposnap
+pluggy==1.5.0
+    # via pytest
+pytest==8.3.2
+smmap==5.0.1
+    # via gitdb

reposnap-0.2.0/requirements.lock

@@ -0,0 +1,22 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+#   generate-hashes: false
+#   universal: false
+
+-e file:.
+gitdb==4.0.11
+    # via gitpython
+gitpython==3.1.43
+    # via reposnap
+pathlib==1.0.1
+    # via reposnap
+pathspec==0.12.1
+    # via reposnap
+smmap==5.0.1
+    # via gitdb

reposnap-0.2.0/src/collect.py

@@ -0,0 +1,4 @@
+from reposnap.interfaces.cli import main
+
+if __name__ == "__main__":
+    main()

reposnap-0.2.0/src/reposnap/core/collector.py

@@ -0,0 +1,21 @@
+# src/reposnap/core/collector.py
+
+from .file_system import FileSystem
+from .git_repo import GitRepo
+from .markdown_generator import MarkdownGenerator
+import pathspec
+
+class ProjectContentCollector:
+    def __init__(self, root_dir: str, output_file: str, structure_only: bool, gitignore_patterns: list):
+        self.root_dir = root_dir
+        self.output_file = output_file
+        self.structure_only = structure_only
+        self.spec = pathspec.PathSpec.from_lines(pathspec.patterns.GitWildMatchPattern, gitignore_patterns)
+        self.file_system = FileSystem(root_dir)
+        self.git_repo = GitRepo(root_dir)
+        self.markdown_generator = MarkdownGenerator()
+
+    def collect_and_generate(self):
+        git_files = self.git_repo.get_git_files()
+        tree_structure = self.file_system.build_tree_structure(git_files)
+        self.markdown_generator.generate_markdown(self.output_file, tree_structure, git_files, self.spec, self.structure_only)

reposnap-0.2.0/src/reposnap/core/file_system.py

@@ -0,0 +1,19 @@
+# src/reposnap/core/file_system.py
+
+from pathlib import Path
+
+class FileSystem:
+    def __init__(self, root_dir: str):
+        self.root_dir = Path(root_dir).resolve()
+
+    def build_tree_structure(self, files):
+        tree = {}
+        for file in files:
+            file_path = Path(file).resolve()
+            relative_path = file_path.relative_to(self.root_dir).as_posix()
+            parts = relative_path.split('/')
+            current_level = tree
+            for part in parts[:-1]:
+                current_level = current_level.setdefault(part, {})
+            current_level[parts[-1]] = relative_path
+        return tree

reposnap-0.2.0/src/reposnap/core/git_repo.py

@@ -0,0 +1,14 @@
+# src/reposnap/core/git_repo.py
+
+from git import Repo, InvalidGitRepositoryError
+
+class GitRepo:
+    def __init__(self, repo_path: str):
+        self.repo_path = repo_path
+
+    def get_git_files(self):
+        try:
+            repo = Repo(self.repo_path)
+            return repo.git.ls_files().splitlines()
+        except InvalidGitRepositoryError:
+            return []

reposnap-0.2.0/src/reposnap/core/markdown_generator.py

@@ -0,0 +1,24 @@
+# src/reposnap/core/markdown_generator.py
+
+from pathlib import Path
+from ..utils.path_utils import format_tree
+
+class MarkdownGenerator:
+    def generate_markdown(self, output_file, tree_structure, git_files, spec, structure_only=False):
+        with open(output_file, 'w') as f:
+            f.write("# Project Structure\n\n")
+            f.write("```\n")
+            for line in format_tree(tree_structure):
+                f.write(line)
+            f.write("```\n\n")
+
+            if not structure_only:
+                for file in git_files:
+                    relative_path = Path(file).relative_to(Path(output_file).parent).as_posix()
+                    if spec and not spec.match_file(relative_path):
+                        # Only read the file if spec is not None and does not match
+                        with open(Path(output_file).parent / file, 'r') as file_content:
+                            f.write(f"## {relative_path}\n\n")
+                            f.write(f"```\n{file_content.read()}\n```\n\n")
+
+        print(f"Markdown file generated: {output_file}")

reposnap-0.2.0/src/reposnap/interfaces/cli.py

@@ -0,0 +1,21 @@
+# src/reposnap/interfaces/cli.py
+
+import argparse
+from reposnap.core.collector import ProjectContentCollector
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate a Markdown representation of a Git repository.')
+    parser.add_argument('path', help='Path to the Git repository.')
+    parser.add_argument('-o', '--output', help='Output Markdown file', default='output.md')
+    parser.add_argument('--structure-only', action='store_true',
+                        help='Only include the file structure without content.')
+    args = parser.parse_args()
+
+    with open(f"{args.path}/.gitignore", 'r') as gitignore:
+        patterns = gitignore.readlines()
+
+    collector = ProjectContentCollector(args.path, args.output, args.structure_only, patterns)
+    collector.collect_and_generate()
+
+if __name__ == "__main__":
+    main()

reposnap-0.2.0/src/reposnap/utils/path_utils.py

@@ -0,0 +1,9 @@
+# src/reposnap/utils/path_utils.py
+
+def format_tree(tree, indent=''):
+    for key, value in tree.items():
+        if isinstance(value, dict):
+            yield f"{indent}{key}/\n"
+            yield from format_tree(value, indent + '    ')
+        else:
+            yield f"{indent}{key}\n"

reposnap-0.2.0/tests/reposnap/test_cli.py

@@ -0,0 +1,77 @@
+# src/reposnap/tests/test_cli.py
+
+import pytest
+from unittest.mock import patch, MagicMock
+import os
+import tempfile
+from reposnap.interfaces.cli import main
+
+def create_file(file_path: str, content: str = ''):
+    """Helper function to create a file with the given content."""
+    with open(file_path, 'w') as f:
+        f.write(content)
+
+def create_directory_structure(base_dir: str, structure: dict):
+    """
+    Helper function to create directories and files based on a given structure.
+    """
+    for name, content in structure.items():
+        path = os.path.join(base_dir, name)
+        if isinstance(content, dict):
+            os.makedirs(path, exist_ok=True)
+            create_directory_structure(path, content)
+        else:
+            create_file(path, content)
+
+@pytest.fixture
+def temp_dir():
+    with tempfile.TemporaryDirectory() as temp_dir:
+        gitignore_content = \
+            """
+            *.txt
+            *.py[oc]
+            .venv
+            """
+
+        structure = {
+            'dir1': {
+                'dir2': {},
+                'file2.py': 'File 2 content',
+            },
+            'file1.txt': 'File 1 content',
+            '.gitignore': gitignore_content,
+            '.venv': {
+                'bin': {
+                    'activate': 'source venv/bin/activate',
+                    'python': 'python3.8',
+                },
+                'lib': {
+                    'python3.8': {
+                        'site-packages': {
+                            'package1': {
+                                '__init__.py': '',
+                                'module1.py': 'def foo(): pass',
+                            },
+                            'package2': {
+                                '__init__.py': '',
+                                'module2.py': 'def bar(): pass',
+                            },
+                        },
+                    },
+                },
+                'include': {},
+            },
+        }
+
+        create_directory_structure(temp_dir, structure)
+        yield temp_dir
+
+@patch('reposnap.interfaces.cli.ProjectContentCollector')
+def test_cli(mock_collector, temp_dir):
+    mock_collector_instance = MagicMock()
+    mock_collector.return_value = mock_collector_instance
+
+    with patch('sys.argv', ['cli.py', str(temp_dir), '--structure-only']):
+        main()
+
+    mock_collector_instance.collect_and_generate.assert_called_once()

reposnap-0.2.0/tests/reposnap/test_collector.py

@@ -0,0 +1,27 @@
+# src/reposnap/tests/test_collector.py
+
+import pytest  # noqa
+from unittest.mock import patch, MagicMock
+from reposnap.core.collector import ProjectContentCollector
+
+
+@patch('reposnap.core.collector.MarkdownGenerator')
+@patch('reposnap.core.collector.FileSystem')
+@patch('reposnap.core.collector.GitRepo')
+def test_collect_and_generate(mock_git_repo, mock_file_system, mock_markdown_generator):
+    # Setup mocks
+    mock_git_repo_instance = MagicMock()
+    mock_file_system_instance = MagicMock()
+    mock_markdown_generator_instance = MagicMock()
+
+    mock_git_repo.return_value = mock_git_repo_instance
+    mock_file_system.return_value = mock_file_system_instance
+    mock_markdown_generator.return_value = mock_markdown_generator_instance
+
+    mock_git_repo_instance.get_git_files.return_value = ['file1.py', 'file2.py']
+    mock_file_system_instance.build_tree_structure.return_value = {'dir': {'file1.py': 'file1.py'}}
+
+    collector = ProjectContentCollector('root_dir', 'output.md', False, ['*.log'])
+    collector.collect_and_generate()
+
+    mock_markdown_generator_instance.generate_markdown.assert_called_once()

reposnap-0.2.0/tests/reposnap/test_file_system.py

@@ -0,0 +1,28 @@
+# src/reposnap/tests/test_file_system.py
+
+import pytest
+from reposnap.core.file_system import FileSystem
+
+@pytest.fixture
+def file_system(tmp_path):
+    # Initialize FileSystem with tmp_path as the root directory
+    return FileSystem(str(tmp_path))
+
+def test_build_tree_structure(file_system, tmp_path):
+    # Ensure intermediate directories are created
+    (tmp_path / 'dir1').mkdir(parents=True, exist_ok=True)
+    (tmp_path / 'dir2').mkdir(parents=True, exist_ok=True)
+
+    # Write files into the created directories
+    (tmp_path / 'dir1' / 'file1.py').write_text('content')
+    (tmp_path / 'dir2' / 'file2.py').write_text('content')
+
+    # Build tree structure based on the files in tmp_path
+    tree_structure = file_system.build_tree_structure([
+        str(tmp_path / 'dir1' / 'file1.py'),
+        str(tmp_path / 'dir2' / 'file2.py')
+    ])
+    assert 'dir1' in tree_structure
+    assert 'file1.py' in tree_structure['dir1']
+    assert 'dir2' in tree_structure
+    assert 'file2.py' in tree_structure['dir2']

reposnap-0.2.0/tests/reposnap/test_git_repo.py

@@ -0,0 +1,16 @@
+# src/reposnap/tests/test_git_repo.py
+
+import pytest  # noqa
+from unittest.mock import patch, MagicMock
+from reposnap.core.git_repo import GitRepo
+
+@patch('reposnap.core.git_repo.Repo')
+def test_get_git_files(mock_repo):
+    mock_repo_instance = MagicMock()
+    mock_repo_instance.git.ls_files.return_value = 'file1.py\nfile2.py'
+    mock_repo.return_value = mock_repo_instance
+
+    git_repo = GitRepo('test_repo')
+    files = git_repo.get_git_files()
+    assert 'file1.py' in files
+    assert 'file2.py' in files

reposnap-0.2.0/tests/reposnap/test_markdown_generator.py

@@ -0,0 +1,15 @@
+# src/reposnap/tests/test_markdown_generator.py
+
+import pytest  # noqa
+from reposnap.core.markdown_generator import MarkdownGenerator
+from unittest.mock import mock_open, patch
+
+def test_generate_markdown():
+    mock_open_func = mock_open()
+    with patch('builtins.open', mock_open_func):
+        markdown_generator = MarkdownGenerator()
+        markdown_generator.generate_markdown('output.md', {'dir': {'file.py': 'file.py'}}, ['file.py'], None)
+
+    mock_open_func.assert_called_once_with('output.md', 'w')
+    handle = mock_open_func()
+    handle.write.assert_called()

reposnap-0.2.0/tests/reposnap/test_path_utils.py

@@ -0,0 +1,15 @@
+# src/reposnap/tests/test_path_utils.py
+
+import pytest  # noqa
+from reposnap.utils.path_utils import format_tree
+
+def test_format_tree():
+    tree = {
+        'dir1': {
+            'file1.py': 'file1.py'
+        },
+        'file2.py': 'file2.py'
+    }
+    formatted = ''.join(format_tree(tree))
+    expected = 'dir1/\n    file1.py\nfile2.py\n'
+    assert formatted == expected