v1.2.1

### Added
-   **Python Docstring Merging**: Implemented a feature to merge the auto-generated header with existing manual module-level docstrings in Python files, preserving user-written content.

### Changed
-   **Test Suite Refactoring**: Significantly refactored the test suite by introducing a `source_processor` fixture. This simplifies test code, removes boilerplate for file creation, and improves readability across all test files.

### Documentation
-   Updated the repository URL in `README.md`.
-   Reorganized `README.md` for better readability by moving the "Supported Languages" section to the top.

Author: Artemonim

CHANGELOG.md

@@ -13,6 +13,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Configuration file format validation
 -   Switching to the Abstract Syntax Tree (AST)
 
+## [1.2.1] - 2025-06-30
+
+### Added
+
+-   **Python Docstring Merging**: Implemented a feature to merge the auto-generated header with existing manual module-level docstrings in Python files, preserving user-written content.
+
+### Changed
+
+-   **Test Suite Refactoring**: Significantly refactored the test suite by introducing a `source_processor` fixture. This simplifies test code, removes boilerplate for file creation, and improves readability across all test files.
+
+### Documentation
+
+-   Updated the repository URL in `README.md`.
+-   Reorganized `README.md` for better readability by moving the "Supported Languages" section to the top.
+
 ## [1.2.0] - 2025-06-29
 
 ### Added
@@ -21,6 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   **Header Preservation**: Implemented intelligent detection to preserve file headers (e.g., shebangs, encoding declarations, Go package definitions, leading comments/imports) across all supported languages.
 -   **Expanded Language Support**: Added initial processing support and type mappings for Java, PowerShell, Delphi, and C.
 -   **Enhanced Testing**: Introduced new test suites for determinism, header preservation, and line number accuracy to ensure core feature reliability.
+-   **Initial release of `agent-docstrings`**
 
 ### Changed
 

README.md

@@ -17,6 +17,22 @@
 
 A command-line tool to auto-generate and update file-level docstrings summarizing classes and functions. Useful for maintaining a high-level overview of your files, especially in projects with code generated or modified by AI assistants.
 
+## Supported Languages
+
+| Language   | File Extensions                     | Features                       |
+| ---------- | ----------------------------------- | ------------------------------ |
+| Python     | `.py`                               | Classes, functions, methods    |
+| Java       | `.java`                             | Classes, methods               |
+| Kotlin     | `.kt`                               | Classes, functions             |
+| Go         | `.go`                               | Functions, methods             |
+| PowerShell | `.ps1`, `.psm1`                     | Functions                      |
+| Delphi     | `.pas`                              | Classes, procedures, functions |
+| C          | `.c`, `.h`                          | Functions                      |
+| C++        | `.cpp`, `.hpp`, `.cc`, `.cxx`, `.h` | Functions, classes             |
+| C#         | `.cs`                               | Classes, methods               |
+| JavaScript | `.js`, `.jsx`                       | Functions, classes             |
+| TypeScript | `.ts`, `.tsx`                       | Functions, classes             |
+
 ## Why?
 
 When working in Cursor and similar IDEs, Agents often start reading files from the beginning. And regarding Cursor's behavior during the script's creation, in normal mode, the model reads 250 lines of code per call, and in MAX mode, 750 lines. However, I have projects with files over 1000 lines of code, which are not very appropriate to divide into smaller files. And anyway, Agent still have to call reading tools for each individual file.
@@ -38,11 +54,6 @@ In addition to the advantage of quick navigation, the initial docstring also ser
 
 This tool is compatible with **Python 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13**.
 
-### Key compatibility features:
-
--   Uses `typing.Union` instead of `|` syntax for Python 3.8/3.9 compatibility
--   Uses `typing.Tuple` instead of built-in `tuple` for type hints
--   Compatible with `from __future__ import annotations`
 -   No dependency on external libraries
 
 ## Installation
@@ -56,7 +67,7 @@ pip install agent-docstrings
 ### From source
 
 ```bash
-git clone https://github.com/yourname/agent-docstrings.git
+git clone https://github.com/Artemonim/agent-docstrings.git
 cd agent-docstrings
 pip install -e .
 ```
@@ -152,22 +163,6 @@ It is important to understand the nuances of this tool to use it effectively. Th
 
 -   **In-Place File Modification**: The tool modifies files directly. It is designed to correctly remove its own previously generated headers, but it might struggle with files that have very complex, pre-existing header comments, potentially leading to incorrect placement of the new header.
 
-## Supported Languages
-
-| Language   | File Extensions                     | Features                       |
-| ---------- | ----------------------------------- | ------------------------------ |
-| Python     | `.py`                               | Classes, functions, methods    |
-| Java       | `.java`                             | Classes, methods               |
-| Kotlin     | `.kt`                               | Classes, functions             |
-| Go         | `.go`                               | Functions, methods             |
-| PowerShell | `.ps1`, `.psm1`                     | Functions                      |
-| Delphi     | `.pas`                              | Classes, procedures, functions |
-| C          | `.c`, `.h`                          | Functions                      |
-| C++        | `.cpp`, `.hpp`, `.cc`, `.cxx`, `.h` | Functions, classes             |
-| C#         | `.cs`                               | Classes, methods               |
-| JavaScript | `.js`, `.jsx`                       | Functions, classes             |
-| TypeScript | `.ts`, `.tsx`                       | Functions, classes             |
-
 ## Examples
 
 ### Python Example

agent_docstrings/__init__.py

@@ -7,4 +7,4 @@
 Attributes:
     __version__ (str): Current version of the *agent-docstrings* package.
 """
-__version__ = "1.2.0" 
+__version__ = "1.2.1" 

agent_docstrings/core.py

@@ -13,7 +13,7 @@
         - _format_header(classes: List[ClassInfo], functions: List[SignatureInfo], language: str, line_offset: int) -> str (line 242)
         - get_preserved_header_end_line(lines: List[str], language: str) -> int (line 262)
         - process_file(path: Path, verbose: bool = False) -> None (line 344)
-        - discover_and_process_files(directories: List[str], verbose: bool = False) -> None (line 414)
+        - discover_and_process_files(directories: List[str], verbose: bool = False) -> None (line 468)
     --- END AUTO-GENERATED DOCSTRING ---
 """
 from __future__ import annotations
@@ -390,15 +390,69 @@ def process_file(path: Path, verbose: bool = False) -> None:
         # * Now create the final header with correct line numbers
         final_header = _format_header(classes, functions, language, line_offset)
 
-        new_content_parts = []
-        if file_prefix:
-            new_content_parts.append(file_prefix)
-        
-        new_content_parts.append(final_header)
-        new_content_parts.append(cleaned_body.strip())
-        
-        # Use single newlines to test composition theory
-        new_content = "\n".join(filter(None, new_content_parts))
+        # Attempt to merge auto-generated header into existing manual docstring for Python
+        merged_body = None
+        if language == "python":
+            # Split cleaned body into lines
+            body_lines = cleaned_body.splitlines()
+            # Find first non-empty line
+            idx = 0
+            while idx < len(body_lines) and body_lines[idx].strip() == "":
+                idx += 1
+            # Check for manual docstring start
+            if idx < len(body_lines) and body_lines[idx].strip().startswith(('"""', "'''")):
+                delim = body_lines[idx].strip()
+                # Ensure it's not an existing auto-generated docstring
+                marker_present = False
+                for i in range(idx, min(idx + 5, len(body_lines))):
+                    if DOCSTRING_START_MARKER in body_lines[i]:
+                        marker_present = True
+                        break
+                if not marker_present:
+                    # Find end of manual docstring
+                    end_idx = None
+                    for j in range(idx + 1, len(body_lines)):
+                        if body_lines[j].strip() == delim:
+                            end_idx = j
+                            break
+                    if end_idx is not None:
+                        manual_inner = body_lines[idx + 1:end_idx]
+                        # Compute auto header content lines with correct offset for merge
+                        # temp_header_lines holds the auto header lines including delimiters
+                        # content_lines length is temp_header_lines minus start/end markers
+                        offset_override = len(temp_header_lines) - 2
+                        # Generate only the header content lines (without triple-quote delimiters)
+                        header_inner = _get_header_content_lines(
+                            classes, functions, language, offset_override
+                        )
+                        merged_lines = []
+                        # Preserve leading blank lines before manual docstring
+                        merged_lines.extend(body_lines[:idx])
+                        # Start merged docstring with manual delimiter
+                        merged_lines.append(delim)
+                        # Insert auto-generated header content
+                        merged_lines.extend(header_inner)
+                        # Insert original manual docstring content
+                        merged_lines.extend(manual_inner)
+                        # Close merged docstring with manual delimiter
+                        merged_lines.append(delim)
+                        # Append rest of body after original docstring
+                        merged_lines.extend(body_lines[end_idx + 1:])
+                        merged_body = "\n".join(merged_lines)
+        if merged_body is not None:
+            if file_prefix:
+                new_content = file_prefix + "\n" + merged_body.lstrip("\n")
+            else:
+                new_content = merged_body.lstrip("\n")
+        else:
+            # Default behavior: insert separate docstring
+            new_content_parts = []
+            if file_prefix:
+                new_content_parts.append(file_prefix)
+            new_content_parts.append(final_header)
+            new_content_parts.append(cleaned_body.strip())
+            # Use single newlines to test composition theory
+            new_content = "\n".join(filter(None, new_content_parts))
 
         if new_content.strip() != original_content.strip():
             path.write_text(new_content, encoding="utf-8", newline="\n")

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-docstrings"
-version = "1.2.0"
+version = "1.2.1"
 description = "A command-line tool to auto-generate and update file-level docstrings summarizing classes and functions. Useful for maintaining a high-level overview of your files, especially in projects with code generated or modified by AI assistants."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
@@ -124,7 +124,7 @@ exclude_lines = [
 ]
 
 [tool.bumpversion]
-current_version = "1.2.0"
+current_version = "1.2.1"
 commit = false
 tag = false
 

tests/conftest.py

@@ -5,19 +5,20 @@
     
     Classes/Functions:
       - Functions:
-        - fixtures_dir() -> Path (line 33)
-        - sample_python_file(tmp_path: Path) -> Iterator[Path] (line 39)
-        - sample_kotlin_file(tmp_path: Path) -> Iterator[Path] (line 61)
-        - sample_javascript_file(tmp_path: Path) -> Iterator[Path] (line 87)
-        - sample_typescript_file(tmp_path: Path) -> Iterator[Path] (line 120)
-        - sample_csharp_file(tmp_path: Path) -> Iterator[Path] (line 155)
-        - sample_cpp_file(tmp_path: Path) -> Iterator[Path] (line 198)
-        - complex_python_file(tmp_path: Path) -> Iterator[Path] (line 249)
-        - python_file_with_existing_header(tmp_path: Path) -> Iterator[Path] (line 357)
-        - multilanguage_project(tmp_path: Path) -> Iterator[Path] (line 390)
-        - empty_files_project(tmp_path: Path) -> Iterator[Path] (line 427)
-        - sample_files_by_language(tmp_path: Path) -> Iterator[Dict[str, Path]] (line 447)
-        - malformed_files_project(tmp_path: Path) -> Iterator[Path] (line 479)
+        - source_processor(tmp_path: Path) (line 36)
+        - fixtures_dir() -> Path (line 64)
+        - sample_python_file(tmp_path: Path) -> Iterator[Path] (line 70)
+        - sample_kotlin_file(tmp_path: Path) -> Iterator[Path] (line 92)
+        - sample_javascript_file(tmp_path: Path) -> Iterator[Path] (line 118)
+        - sample_typescript_file(tmp_path: Path) -> Iterator[Path] (line 151)
+        - sample_csharp_file(tmp_path: Path) -> Iterator[Path] (line 186)
+        - sample_cpp_file(tmp_path: Path) -> Iterator[Path] (line 229)
+        - complex_python_file(tmp_path: Path) -> Iterator[Path] (line 280)
+        - python_file_with_existing_header(tmp_path: Path) -> Iterator[Path] (line 388)
+        - multilanguage_project(tmp_path: Path) -> Iterator[Path] (line 421)
+        - empty_files_project(tmp_path: Path) -> Iterator[Path] (line 458)
+        - sample_files_by_language(tmp_path: Path) -> Iterator[Dict[str, Path]] (line 478)
+        - malformed_files_project(tmp_path: Path) -> Iterator[Path] (line 510)
     --- END AUTO-GENERATED DOCSTRING ---
 """
 from __future__ import annotations
@@ -28,6 +29,36 @@
 
 import pytest
 
+from agent_docstrings.core import process_file
+
+
+@pytest.fixture
+def source_processor(tmp_path: Path):
+    """A factory fixture that returns a helper function to process source code.
+
+    The helper function creates a temporary file with the given source code,
+    runs the main `process_file` logic on it, and returns the results.
+
+    Returns:
+        A callable that takes a filename and source code string, and returns
+        a tuple containing:
+        - The processed file content (str)
+        - The processed file content as a list of lines (list[str])
+        - The path to the processed file (Path)
+    """
+
+    def _process(
+        filename: str, source_code: str, verbose: bool = False
+    ) -> tuple[str, list[str], Path]:
+        """Creates a file with source_code, runs process_file, and returns content."""
+        source_path = tmp_path / filename
+        source_path.write_text(source_code, encoding="utf-8")
+        process_file(source_path, verbose=verbose)
+        content = source_path.read_text(encoding="utf-8")
+        return content, content.splitlines(), source_path
+
+    return _process
+
 
 @pytest.fixture(scope="session")
 def fixtures_dir() -> Path: