docuflow 0.3.0__tar.gz

docuflow-0.3.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: docuflow
+Version: 0.3.0
+Summary: AI-Native Documentation & Architecture Maintenance Agent
+Author: DocuFlow Developer
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: gitpython>=3.1.30
+Requires-Dist: google-generativeai>=0.3.0
+Requires-Dist: openai>=1.0.0

docuflow-0.3.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "docuflow"
+version = "0.3.0"
+description = "AI-Native Documentation & Architecture Maintenance Agent"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "DocuFlow Developer" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "pydantic>=2.0.0",
+    "toml>=0.10.2",
+    "gitpython>=3.1.30",
+    "google-generativeai>=0.3.0",
+    "openai>=1.0.0",
+]
+
+[project.scripts]
+docuflow = "docuflow.main:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]

docuflow-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

docuflow-0.3.0/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+if __name__ == "__main__":
+    setup()

docuflow-0.3.0/src/docuflow/__init__.py

@@ -0,0 +1,5 @@
+"""
+DocuFlow: AI-Native Documentation & Architecture Maintenance Agent
+"""
+
+__version__ = "0.3.0"

docuflow-0.3.0/src/docuflow/ai_engine.py

@@ -0,0 +1,179 @@
+import os
+from pathlib import Path
+from typing import List, Optional, Tuple
+from google import generativeai as genai
+from openai import OpenAI
+
+from docuflow.config import DocuFlowConfig
+from docuflow.context_builder import ImpactAnalysis
+
+def find_associated_docs(filepath: str, docs_dir: Path) -> List[Path]:
+    """
+    Scans the documentation directory and matches markdown files that refer
+    to the given code filepath, filename, or module parent.
+    Normalizes casing, underscores, and hyphens to maximize match accuracy.
+    """
+    associated: List[Path] = []
+    if not docs_dir.exists():
+        return associated
+
+    filename = Path(filepath).name
+    basename = Path(filepath).stem
+    
+    # Pre-calculate normalized flat values for code file
+    flat_basename = basename.replace("_", "").replace("-", "").lower()
+    flat_filename = filename.replace("_", "").replace("-", "").lower()
+    
+    for md_file in docs_dir.glob("**/*.md"):
+        # Skip hidden or temporary files
+        if md_file.name.startswith("."):
+            continue
+        try:
+            content = md_file.read_text(encoding="utf-8")
+            flat_content = content.replace("_", "").replace("-", "").lower()
+            flat_md_filename = md_file.name.replace("_", "").replace("-", "").lower()
+            
+            # Match if:
+            # - Flat filename stem (e.g., 'gitutils') is in the flat markdown content
+            # - Flat filename (e.g., 'gitutils.py') is in the flat markdown content
+            # - Flat filename stem (e.g., 'gitutils') matches the flat markdown filename stem
+            if (flat_filename in flat_content or 
+                flat_basename in flat_content or 
+                flat_basename in flat_md_filename):
+                associated.append(md_file)
+        except Exception:
+            pass
+            
+    return associated
+
+def format_ast_summary(analysis: ImpactAnalysis) -> str:
+    """
+    Formats a clean, human-readable summary of the AST modifications for the prompt.
+    """
+    summary = []
+    if analysis.added_entities:
+        summary.append("Added Code Entities:")
+        for ent in analysis.added_entities:
+            summary.append(f"  - {ent.type.capitalize()} `{ent.name}` with signature: `{ent.signature}`")
+    if analysis.modified_entities:
+        summary.append("Modified Code Entities:")
+        for ent in analysis.modified_entities:
+            summary.append(f"  - {ent.type.capitalize()} `{ent.name}` with signature: `{ent.signature}`")
+    if analysis.removed_entities:
+        summary.append("Removed/Deleted Code Entities:")
+        for ent in analysis.removed_entities:
+            summary.append(f"  - {ent.type.capitalize()} `{ent.name}`")
+            
+    return "\n".join(summary) if summary else "No high-level AST structural changes."
+
+def build_orchestrator_prompt(
+    rules_content: str,
+    md_content: str,
+    md_filename: str,
+    analysis: ImpactAnalysis
+) -> str:
+    """
+    Assembles the detailed prompt for the AI documentation agent, passing the style rules,
+    current markdown file content, git diff, and AST modifications.
+    """
+    ast_summary = format_ast_summary(analysis)
+    
+    prompt = f"""You are the DocuFlow AI Documentation Agent. Your job is to update the technical documentation markdown file to accurately reflect recent code modifications.
+
+--- SYSTEM STYLING & FORMATTING RULES (documentation-rules.md) ---
+{rules_content}
+
+--- TARGET TECHNICAL DOCUMENT TO UPDATE ---
+File Name: {md_filename}
+Content:
+```markdown
+{md_content}
+```
+
+--- RAW CODE DIFF MODIFICATIONS ---
+File: {analysis.filepath}
+Diff:
+```diff
+{analysis.raw_diff}
+```
+
+--- EXTRACTED CODE AST CHANGES ---
+{ast_summary}
+
+--- MANDATORY INSTRUCTIONS ---
+1. Analyze the raw code changes and the high-level AST modifications.
+2. Update the target documentation file so it perfectly matches the new code structure (e.g., class names, function parameters, return types, or architectural flows).
+3. Perform a NON-DESTRUCTIVE update: only modify, add, or delete details that directly correspond to the code changes. Do NOT touch, rewrite, or delete surrounding unrelated text, descriptions, or headers.
+4. Synchronize or update any visual Mermaid diagrams inside the documentation to match the new code relationships or state flows, adhering strictly to the Mermaid standards (e.g., wrap node labels containing special characters in double quotes).
+5. Keep formatting intact. Return ONLY the complete, updated markdown content. Do not include any introductory remarks, conversational preambles, or markdown fences wrap outside the file itself.
+"""
+    return prompt
+
+def execute_llm_update(
+    config: DocuFlowConfig,
+    prompt: str
+) -> Tuple[Optional[str], str]:
+    """
+    Executes the LLM request using the active configuration provider (Gemini or OpenAI).
+    Returns a tuple of (updated_markdown_content, error_message).
+    """
+    provider = config.ai.provider.lower()
+    model_name = config.ai.model
+    temp = config.ai.temperature
+    max_t = config.ai.max_tokens
+
+    if provider == "gemini":
+        api_key = os.environ.get("GEMINI_API_KEY")
+        if not api_key:
+            return None, "GEMINI_API_KEY environment variable is not set."
+        try:
+            genai.configure(api_key=api_key)
+            model = genai.GenerativeModel(
+                model_name=model_name,
+                generation_config={
+                    "temperature": temp,
+                    "max_output_tokens": max_t
+                }
+            )
+            response = model.generate_content(prompt)
+            content = response.text.strip()
+            
+            # Strip outer markdown fences if returned
+            if content.startswith("```markdown"):
+                content = content[11:]
+                if content.endswith("```"):
+                    content = content[:-3]
+            elif content.startswith("```") and content.endswith("```"):
+                content = content[3:-3]
+                
+            return content.strip(), ""
+        except Exception as e:
+            return None, f"Gemini API call failed: {e}"
+
+    elif provider == "openai":
+        api_key = os.environ.get("OPENAI_API_KEY")
+        if not api_key:
+            return None, "OPENAI_API_KEY environment variable is not set."
+        try:
+            client = OpenAI(api_key=api_key)
+            response = client.chat.completions.create(
+                model=model_name,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=temp,
+                max_tokens=max_t
+            )
+            content = response.choices[0].message.content.strip()
+            
+            # Strip outer markdown fences if returned
+            if content.startswith("```markdown"):
+                content = content[11:]
+                if content.endswith("```"):
+                    content = content[:-3]
+            elif content.startswith("```") and content.endswith("```"):
+                content = content[3:-3]
+                
+            return content.strip(), ""
+        except Exception as e:
+            return None, f"OpenAI API call failed: {e}"
+
+    return None, f"Unsupported AI provider: {provider}"

docuflow-0.3.0/src/docuflow/config.py

@@ -0,0 +1,57 @@
+import os
+from pathlib import Path
+from typing import List, Optional
+from pydantic import BaseModel, Field
+import toml
+
+class ProjectConfig(BaseModel):
+    name: str = "DocuFlow"
+    watch_dirs: List[str] = Field(default_factory=lambda: ["src"])
+
+class DocumentationConfig(BaseModel):
+    docs_dir: str = "docs"
+    patterns: List[str] = Field(default_factory=lambda: ["*.md"])
+    rules_dir: str = ".agents/rules"
+    workflows_dir: str = ".agents/workflows"
+
+class AIConfig(BaseModel):
+    provider: str = "gemini"
+    model: str = "gemini-1.5-pro"
+    temperature: float = 0.2
+    max_tokens: int = 4096
+
+class GitConfig(BaseModel):
+    target_branch: str = "main"
+    include_unstaged: bool = True
+    include_staged: bool = True
+
+class DocuFlowConfig(BaseModel):
+    project: ProjectConfig = Field(default_factory=ProjectConfig)
+    documentation: DocumentationConfig = Field(default_factory=DocumentationConfig)
+    ai: AIConfig = Field(default_factory=AIConfig)
+    git: GitConfig = Field(default_factory=GitConfig)
+
+def load_config(config_path: Optional[Path] = None) -> DocuFlowConfig:
+    """
+    Loads and parses the docuflow.toml configuration file.
+    If no path is provided, checks the current working directory and its parents.
+    """
+    if config_path is None:
+        # Search upward from the current working directory for docuflow.toml
+        current_dir = Path.cwd()
+        for parent in [current_dir] + list(current_dir.parents):
+            candidate = parent / "docuflow.toml"
+            if candidate.is_file():
+                config_path = candidate
+                break
+    
+    if config_path and config_path.is_file():
+        try:
+            with open(config_path, "r", encoding="utf-8") as f:
+                data = toml.load(f)
+            return DocuFlowConfig(**data)
+        except Exception:
+            # Fallback to default config on parse error
+            pass
+            
+    return DocuFlowConfig()

docuflow-0.3.0/src/docuflow/context_builder.py

@@ -0,0 +1,83 @@
+from pathlib import Path
+from typing import Dict, List, Optional
+from pydantic import BaseModel, Field
+
+from docuflow.parser import EntityInfo, parse_code_structure
+from docuflow.git_utils import run_git_command, is_git_repo
+
+class ImpactAnalysis(BaseModel):
+    """
+    Represents the full structural impact analysis of changes made to a file.
+    """
+    filepath: str
+    added_entities: List[EntityInfo] = Field(default_factory=list)
+    modified_entities: List[EntityInfo] = Field(default_factory=list)
+    removed_entities: List[EntityInfo] = Field(default_factory=list)
+    raw_diff: str = ""
+
+def get_git_file_content(filepath: str, ref: str = "HEAD", cwd: Optional[Path] = None) -> str:
+    """
+    Retrieves the content of a file from Git history at a specific reference.
+    Returns an empty string if the file did not exist yet (e.g. newly added).
+    """
+    try:
+        return run_git_command(["show", f"{ref}:{filepath}"], cwd=cwd)
+    except Exception:
+        return ""
+
+def build_impact_analysis(filepath: str, raw_diff: str, base_ref: str = "HEAD", cwd: Optional[Path] = None) -> ImpactAnalysis:
+    """
+    Compares the AST structures of a file between its Git base state and current filesystem state
+    to identify added, modified, or removed classes, functions, and methods.
+    """
+    # 1. Fetch original content from Git
+    original_content = get_git_file_content(filepath, ref=base_ref, cwd=cwd)
+    
+    # 2. Fetch current content from local disk
+    current_path = (cwd or Path.cwd()) / filepath
+    current_content = ""
+    if current_path.is_file():
+        try:
+            current_content = current_path.read_text(encoding="utf-8")
+        except Exception:
+            pass
+            
+    # 3. For Python files, parse and compare ASTs
+    if filepath.endswith(".py"):
+        old_entities = {e.name: e for e in parse_code_structure(original_content)}
+        new_entities = {e.name: e for e in parse_code_structure(current_content)}
+        
+        added_entities = []
+        modified_entities = []
+        removed_entities = []
+        
+        # Check added and modified entities
+        for name, new_ent in new_entities.items():
+            if name not in old_entities:
+                added_entities.append(new_ent)
+            else:
+                old_ent = old_entities[name]
+                # Consider it modified if signature or docstring changes, or if the size/bounds of implementation changed
+                if (new_ent.signature != old_ent.signature or
+                    new_ent.docstring != old_ent.docstring or
+                    (new_ent.line_end - new_ent.line_start) != (old_ent.line_end - old_ent.line_start)):
+                    modified_entities.append(new_ent)
+                    
+        # Check removed entities
+        for name, old_ent in old_entities.items():
+            if name not in new_entities:
+                removed_entities.append(old_ent)
+                
+        return ImpactAnalysis(
+            filepath=filepath,
+            added_entities=added_entities,
+            modified_entities=modified_entities,
+            removed_entities=removed_entities,
+            raw_diff=raw_diff
+        )
+        
+    # Non-python files just map the raw diff without AST structures
+    return ImpactAnalysis(
+        filepath=filepath,
+        raw_diff=raw_diff
+    )

docuflow-0.3.0/src/docuflow/git_utils.py

@@ -0,0 +1,188 @@
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional
+from pydantic import BaseModel
+
+class FileChange(BaseModel):
+    """
+    Represents a single file change extracted from Git.
+    """
+    filepath: str
+    change_type: str  # 'A' (Added), 'M' (Modified), 'D' (Deleted), 'R' (Renamed), etc.
+    diff: str
+    module: str
+
+def run_git_command(args: List[str], cwd: Optional[Path] = None) -> str:
+    """
+    Executes a git command and returns the stdout string.
+    Raises RuntimeError if the command fails.
+    """
+    try:
+        result = subprocess.run(
+            ["git"] + args,
+            capture_output=True,
+            text=True,
+            check=True,
+            cwd=cwd or Path.cwd()
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"Git command failed: {' '.join(e.cmd)}\nError: {e.stderr.strip()}") from e
+    except FileNotFoundError as e:
+        raise RuntimeError("Git executable not found on system path.") from e
+
+def is_git_repo(cwd: Optional[Path] = None) -> bool:
+    """
+    Checks if the given directory is inside a git repository.
+    """
+    try:
+        output = run_git_command(["rev-parse", "--is-inside-work-tree"], cwd=cwd)
+        return output == "true"
+    except RuntimeError:
+        return False
+
+def get_git_root(cwd: Optional[Path] = None) -> Path:
+    """
+    Gets the absolute Path of the Git repository root.
+    """
+    output = run_git_command(["rev-parse", "--show-toplevel"], cwd=cwd)
+    return Path(output).resolve()
+
+def extract_module(filepath: str) -> str:
+    """
+    Helper to extract the module/folder name for grouping.
+    e.g., 'src/auth/login.py' -> 'src/auth'
+          'src/main.py' -> 'src'
+          'plan.md' -> '.'
+    """
+    path = Path(filepath)
+    parts = path.parts
+    if len(parts) > 2:
+        return str(Path(*parts[:2]))
+    elif len(parts) == 2:
+        return parts[0]
+    else:
+        return "."
+
+def parse_name_status_line(line: str) -> Optional[tuple[str, str]]:
+    """
+    Parses a line from `git diff --name-status`
+    e.g., 'M\tsrc/main.py' -> ('M', 'src/main.py')
+    """
+    if not line.strip():
+        return None
+    parts = line.split("\t")
+    if len(parts) >= 2:
+        # handle renamed status which could be 'R100\told_name\tnew_name'
+        status = parts[0][0]  # Just take the first character (e.g. 'R', 'M', 'A')
+        filepath = parts[-1]  # Take the final destination file path
+        return status, filepath
+    return None
+
+def get_file_diff(filepath: str, extra_args: List[str], cwd: Optional[Path] = None) -> str:
+    """
+    Gets the diff content for a specific file.
+    """
+    try:
+        # run git diff with specific arguments and targeting the file
+        return run_git_command(["diff"] + extra_args + ["--", filepath], cwd=cwd)
+    except RuntimeError:
+        return ""
+
+def get_unstaged_changes(cwd: Optional[Path] = None) -> List[FileChange]:
+    """
+    Retrieves all unstaged file modifications and their diffs.
+    """
+    if not is_git_repo(cwd):
+        return []
+    
+    # Get the status list of unstaged files
+    status_output = run_git_command(["diff", "--name-status"], cwd=cwd)
+    changes = []
+    
+    for line in status_output.splitlines():
+        parsed = parse_name_status_line(line)
+        if not parsed:
+            continue
+        status, filepath = parsed
+        # Get diff for this specific unstaged file
+        diff = get_file_diff(filepath, [], cwd=cwd)
+        changes.append(FileChange(
+            filepath=filepath,
+            change_type=status,
+            diff=diff,
+            module=extract_module(filepath)
+        ))
+        
+    return changes
+
+def get_staged_changes(cwd: Optional[Path] = None) -> List[FileChange]:
+    """
+    Retrieves all staged file modifications and their diffs.
+    """
+    if not is_git_repo(cwd):
+        return []
+    
+    # Get the status list of staged files
+    status_output = run_git_command(["diff", "--cached", "--name-status"], cwd=cwd)
+    changes = []
+    
+    for line in status_output.splitlines():
+        parsed = parse_name_status_line(line)
+        if not parsed:
+            continue
+        status, filepath = parsed
+        # Get diff for this specific staged file
+        diff = get_file_diff(filepath, ["--cached"], cwd=cwd)
+        changes.append(FileChange(
+            filepath=filepath,
+            change_type=status,
+            diff=diff,
+            module=extract_module(filepath)
+        ))
+        
+    return changes
+
+def get_branch_diff(target_branch: str, cwd: Optional[Path] = None) -> List[FileChange]:
+    """
+    Retrieves file modifications and diffs between current branch (HEAD) and a target branch/commit.
+    Uses target_branch...HEAD (triple dot) to see changes introduced on current branch since it split from target.
+    """
+    if not is_git_repo(cwd):
+        return []
+    
+    try:
+        # Check if the target branch exists or can be resolved
+        run_git_command(["rev-parse", "--verify", target_branch], cwd=cwd)
+    except RuntimeError:
+        # Fallback to single-dot or direct branch comparison if the reference is different
+        pass
+
+    # Get status list comparing the target branch to current HEAD
+    status_output = run_git_command(["diff", f"{target_branch}...HEAD", "--name-status"], cwd=cwd)
+    changes = []
+    
+    for line in status_output.splitlines():
+        parsed = parse_name_status_line(line)
+        if not parsed:
+            continue
+        status, filepath = parsed
+        # Get diff comparison
+        diff = get_file_diff(filepath, [f"{target_branch}...HEAD"], cwd=cwd)
+        changes.append(FileChange(
+            filepath=filepath,
+            change_type=status,
+            diff=diff,
+            module=extract_module(filepath)
+        ))
+        
+    return changes
+
+def group_changes_by_module(changes: List[FileChange]) -> Dict[str, List[FileChange]]:
+    """
+    Groups a list of FileChange objects by their module folder.
+    """
+    grouped: Dict[str, List[FileChange]] = {}
+    for change in changes:
+        grouped.setdefault(change.module, []).append(change)
+    return grouped