docuflow 0.3.0__py3-none-any.whl

docuflow/__init__.py

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

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/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/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/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

docuflow/main.py

@@ -0,0 +1,534 @@
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.status import Status
+from rich.markdown import Markdown
+from rich import print as rprint
+
+from docuflow.config import load_config, DocuFlowConfig
+from docuflow.git_utils import (
+    is_git_repo,
+    get_unstaged_changes,
+    get_staged_changes,
+    get_branch_diff,
+    group_changes_by_module,
+    FileChange,
+)
+from docuflow.context_builder import build_impact_analysis
+from docuflow.ai_engine import (
+    find_associated_docs,
+    execute_llm_update,
+    build_orchestrator_prompt,
+)
+
+app = typer.Typer(
+    name="docuflow",
+    help="🤖 AI-Native Documentation & Architecture Maintenance Agent",
+    no_args_is_help=True,
+)
+console = Console()
+
+@app.command("init")
+def init_cmd(
+    config_path: Path = typer.Option(
+        Path("docuflow.toml"),
+        "--config",
+        "-c",
+        help="Path where the configuration file should be created."
+    )
+):
+    """
+    Initialize a new DocuFlow configuration and workspace structure.
+    """
+    console.print("[bold blue]⚡ Initializing DocuFlow Project...[/bold blue]\n")
+    
+    # 1. Create docuflow.toml if not exists
+    if config_path.exists():
+        console.print(f"[yellow]⚠️  Configuration file '{config_path}' already exists. Skipping creation.[/yellow]")
+    else:
+        # Create a basic default template config
+        config_content = """# DocuFlow Configuration Template
+# This file controls targeting, rules, and LLM providers for the DocuFlow agent.
+
+[project]
+name = "DocuFlow"
+watch_dirs = ["src"]
+
+[documentation]
+docs_dir = "docs"
+patterns = ["*.md"]
+rules_dir = ".agents/rules"
+workflows_dir = ".agents/workflows"
+
+[ai]
+provider = "gemini"
+model = "gemini-1.5-pro"
+temperature = 0.2
+max_tokens = 4096
+
+[git]
+target_branch = "main"
+include_unstaged = true
+include_staged = true
+"""
+        try:
+            config_path.write_text(config_content, encoding="utf-8")
+            console.print(f"[green]✅ Created configuration template: [bold]{config_path}[/bold][/green]")
+        except Exception as e:
+            console.print(f"[red]❌ Failed to create config file: {e}[/red]")
+            raise typer.Exit(code=1)
+
+    # 2. Create docs directory if it doesn't exist
+    config = load_config(config_path)
+    docs_dir = Path(config.documentation.docs_dir)
+    if not docs_dir.exists():
+        docs_dir.mkdir(parents=True, exist_ok=True)
+        console.print(f"[green]✅ Created documentation directory: [bold]{docs_dir}/[/bold][/green]")
+    else:
+        console.print(f"[yellow]ℹ️  Documentation directory '{docs_dir}/' already exists.[/yellow]")
+
+    # 3. Create .agents rules/workflows subdirectories if needed
+    rules_dir = Path(config.documentation.rules_dir)
+    rules_dir.mkdir(parents=True, exist_ok=True)
+    
+    workflows_dir = Path(config.documentation.workflows_dir)
+    workflows_dir.mkdir(parents=True, exist_ok=True)
+    
+    console.print("\n[bold green]🎉 DocuFlow project successfully initialized! Ready to manage technical documentation.[/bold green]")
+
+@app.command("run")
+def run_cmd(
+    config_path: Optional[Path] = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to the docuflow.toml configuration file."
+    ),
+    target_branch: Optional[str] = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Target branch/ref to compare against (e.g., origin/main)."
+    ),
+    staged: Optional[bool] = typer.Option(
+        None,
+        "--staged/--no-staged",
+        help="Force include/exclude staged changes in the analysis."
+    ),
+    unstaged: Optional[bool] = typer.Option(
+        None,
+        "--unstaged/--no-unstaged",
+        help="Force include/exclude unstaged changes in the analysis."
+    ),
+):
+    """
+    Analyze repository changes, group by module, and show what DocuFlow will process.
+    """
+    console.print("[bold blue]🔍 DocuFlow Git Analysis Engine[/bold blue]\n")
+    
+    config = load_config(config_path)
+    
+    # Resolve overrides vs config file defaults
+    inc_staged = staged if staged is not None else config.git.include_staged
+    inc_unstaged = unstaged if unstaged is not None else config.git.include_unstaged
+    branch = target_branch or config.git.target_branch
+
+    if not is_git_repo():
+        console.print("[bold red]❌ Error: Current directory is not a Git repository.[/bold red]")
+        raise typer.Exit(code=1)
+
+    all_changes: List[FileChange] = []
+    
+    with console.status("[bold green]Analyzing workspace changes...") as status:
+        # Get staged changes
+        if inc_staged:
+            try:
+                staged_changes = get_staged_changes()
+                # Label change_type inside representation for display if needed
+                all_changes.extend(staged_changes)
+            except Exception as e:
+                console.print(f"[yellow]⚠️ Could not fetch staged changes: {e}[/yellow]")
+
+        # Get unstaged changes
+        if inc_unstaged:
+            try:
+                unstaged_changes = get_unstaged_changes()
+                all_changes.extend(unstaged_changes)
+            except Exception as e:
+                console.print(f"[yellow]⚠️ Could not fetch unstaged changes: {e}[/yellow]")
+
+        # Get branch difference if specified or fallback
+        if branch and not all_changes:
+            try:
+                branch_changes = get_branch_diff(branch)
+                all_changes.extend(branch_changes)
+            except Exception as e:
+                console.print(f"[yellow]⚠️ Could not fetch diff against '{branch}': {e}[/yellow]")
+
+    if not all_changes:
+        console.print("[bold green]✨ No file modifications detected! Documentation is up to date.[/bold green]")
+        return
+
+    # Group changes by module
+    grouped = group_changes_by_module(all_changes)
+    
+    # Display the summary table
+    table = Table(title="Detected Code Changes grouped by Modules", title_style="bold magenta")
+    table.add_column("Module / Folder", style="cyan", no_wrap=True)
+    table.add_column("File Path", style="green")
+    table.add_column("Status", style="yellow", justify="center")
+    table.add_column("Lines of Diff", style="white", justify="right")
+
+    total_changes = 0
+    impact_summaries = []
+
+    for module, changes in grouped.items():
+        for change in changes:
+            diff_lines = len(change.diff.splitlines()) if change.diff else 0
+            # Friendly change type labels
+            status_map = {"A": "Added 🆕", "M": "Modified 📝", "D": "Deleted 🗑️", "R": "Renamed 🔄"}
+            status_label = status_map.get(change.change_type, change.change_type)
+            
+            table.add_row(module, change.filepath, status_label, str(diff_lines))
+            total_changes += 1
+
+            # Extract AST impact on Python code modifications
+            if change.filepath.endswith(".py"):
+                try:
+                    analysis = build_impact_analysis(change.filepath, change.diff)
+                    if analysis.added_entities or analysis.modified_entities or analysis.removed_entities:
+                        impact_summaries.append((change.filepath, analysis))
+                except Exception:
+                    pass
+
+    console.print(table)
+    console.print(f"\n[bold green]📦 Total files changed: {total_changes} across {len(grouped)} modules.[/bold green]")
+
+    # Render Deep AST Structural impact report
+    if impact_summaries:
+        console.print("\n[bold magenta]🔬 Deep AST Code Impact Analysis[/bold magenta]")
+        for filepath, analysis in impact_summaries:
+            console.print(f"  [bold cyan]• {filepath}[/bold cyan]")
+            
+            if analysis.added_entities:
+                for ent in analysis.added_entities:
+                    doc_flag = " 📝 [dim](has docstring)[/dim]" if ent.docstring else ""
+                    console.print(f"    [green]🆕 [Added] {ent.type} [bold]{ent.signature}[/bold][/green]{doc_flag}")
+                    
+            if analysis.modified_entities:
+                for ent in analysis.modified_entities:
+                    doc_flag = " 📝 [dim](has docstring)[/dim]" if ent.docstring else ""
+                    console.print(f"    [yellow]📝 [Modified] {ent.type} [bold]{ent.signature}[/bold][/yellow]{doc_flag}")
+                    
+            if analysis.removed_entities:
+                for ent in analysis.removed_entities:
+                    console.print(f"    [red]🗑️ [Removed] {ent.type} [bold]{ent.name}[/bold][/red]")
+
+    # Showcase what Phase 3 will execute (LLM Execution)
+    console.print(
+        Panel(
+            "[bold white]🚀 Phase 1 & Phase 2 Complete![/bold white]\n"
+            "The repository diff has been parsed, and code entities have been extracted at the AST level.\n"
+            "In Phase 3, this structural impact context will trigger the AI documentation agent "
+            "to perform context-aware updates to relevant markdown files and sync visual Mermaid flowcharts.",
+            title="Next Steps (AI Documentation Engine)",
+            border_style="magenta",
+        )
+    )
+
+def check_markdown_content(content: str) -> List[str]:
+    """
+    Runs a single-pass, stateful line parser to check markdown alignment with guidelines.
+    Returns a list of issues found.
+    """
+    issues = []
+    lines = content.splitlines()
+    in_code_block = False
+    in_mermaid = False
+    h1_count = 0
+    todos = []
+    unspecified_blocks = []
+    mermaid_issues = []
+
+    for i, line in enumerate(lines):
+        # Handle code block state toggle
+        if line.startswith("```"):
+            if not in_code_block:
+                specifier = line[3:].strip()
+                if not specifier:
+                    unspecified_blocks.append(i + 1)
+                if specifier == "mermaid":
+                    in_mermaid = True
+                in_code_block = True
+            else:
+                in_code_block = False
+                in_mermaid = False
+            continue
+
+        if in_code_block:
+            if in_mermaid:
+                if "[" in line and "]" in line and '"' not in line and ("(" in line or ")" in line):
+                    mermaid_issues.append(i + 1)
+            continue
+
+        # Outside code blocks: Check for guidelines
+        if line.startswith("# ") and not line.startswith("##"):
+            h1_count += 1
+        
+        if "TODO" in line or "FIXME" in line:
+            todos.append(i + 1)
+
+    if h1_count == 0:
+        issues.append("Missing single standard H1 header (`# Title`)")
+    elif h1_count > 1:
+        issues.append(f"Multiple H1 headers found ({h1_count})")
+
+    if todos:
+        issues.append(f"Contains TODO / placeholders on line(s): {', '.join(map(str, todos))}")
+
+    if unspecified_blocks:
+        issues.append(f"Code block missing language specifier on line(s): {', '.join(map(str, unspecified_blocks))}")
+
+    if mermaid_issues:
+        issues.append(f"Mermaid label with special characters missing quotes on line(s): {', '.join(map(str, mermaid_issues))}")
+
+    return issues
+
+@app.command("check")
+def check_cmd(
+    config_path: Optional[Path] = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to the docuflow.toml configuration file."
+    ),
+    docs_dir: Optional[Path] = typer.Option(
+        None,
+        "--docs-dir",
+        "-d",
+        help="Override path to the documentation directory."
+    )
+):
+    """
+    Perform a health check on technical documentation files to ensure alignment with rules.
+    """
+    console.print("[bold blue]🩺 DocuFlow Documentation Health Checker[/bold blue]\n")
+    
+    config = load_config(config_path)
+    target_docs = docs_dir or Path(config.documentation.docs_dir)
+    
+    if not target_docs.exists():
+        console.print(f"[bold red]❌ Error: Documentation directory '{target_docs}' does not exist.[/bold red]")
+        console.print("[yellow]💡 Run [bold]docuflow init[/bold] to set up the default structure.[/yellow]")
+        raise typer.Exit(code=1)
+
+    md_files = list(target_docs.glob("**/*.md"))
+    if not md_files:
+        console.print(f"[yellow]⚠️ No markdown (.md) files found in documentation directory '{target_docs}'.[/yellow]")
+        return
+
+    console.print(f"Checking {len(md_files)} markdown files in '[bold]{target_docs}[/bold]'...\n")
+    
+    table = Table(title="Documentation Health Check Report", title_style="bold magenta")
+    table.add_column("Markdown File", style="cyan")
+    table.add_column("Status", style="bold", justify="center")
+    table.add_column("Details / Recommendations", style="white")
+
+    passed_count = 0
+    failed_count = 0
+
+    for md_file in md_files:
+        issues = []
+        try:
+            content = md_file.read_text(encoding="utf-8")
+            issues = check_markdown_content(content)
+        except Exception as e:
+            issues.append(f"Failed to read file: {e}")
+
+        # Determine file path relative to workspace root
+        try:
+            rel_path = md_file.relative_to(Path.cwd())
+        except ValueError:
+            rel_path = md_file
+
+        if not issues:
+            table.add_row(str(rel_path), "[bold green]PASS ✅[/bold green]", "Perfect! Alignment with all formatting rules.")
+            passed_count += 1
+        else:
+            issues_joined = "; ".join(issues)
+            table.add_row(str(rel_path), "[bold red]FAIL ❌[/bold red]", f"[yellow]{issues_joined}[/yellow]")
+            failed_count += 1
+
+    console.print(table)
+    
+    console.print(f"\n[bold]Summary:[/bold] [green]{passed_count} Passed[/green], [red]{failed_count} Failed[/red].")
+    
+    if failed_count > 0:
+        console.print("\n[bold yellow]💡 Recommendation:[/bold yellow] Clean up the failed files above to comply with [bold]documentation-rules.md[/bold].")
+
+@app.command("sync")
+def sync_cmd(
+    config_path: Optional[Path] = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to the docuflow.toml configuration file."
+    ),
+    target_branch: Optional[str] = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Target branch/ref to compare against (e.g., origin/main)."
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-d",
+        help="Run in dry-run mode. Generates and displays prompts without calling LLM or writing files."
+    )
+):
+    """
+    Automatically synchronize technical markdown documentation with recent code updates using AI.
+    """
+    console.print("[bold blue]🤖 DocuFlow AI Documentation Orchestration[/bold blue]\n")
+    
+    config = load_config(config_path)
+    branch = target_branch or config.git.target_branch
+
+    if not is_git_repo():
+        console.print("[bold red]❌ Error: Current directory is not a Git repository.[/bold red]")
+        raise typer.Exit(code=1)
+
+    # 1. Fetch changed files
+    all_changes: List[FileChange] = []
+    try:
+        if config.git.include_staged:
+            all_changes.extend(get_staged_changes())
+        if config.git.include_unstaged:
+            all_changes.extend(get_unstaged_changes())
+        if branch and not all_changes:
+            all_changes.extend(get_branch_diff(branch))
+    except Exception as e:
+        console.print(f"[bold red]❌ Error fetching changes: {e}[/bold red]")
+        raise typer.Exit(code=1)
+
+    if not all_changes:
+        console.print("[bold green]✨ No code modifications detected! Documentation is up to date.[/bold green]")
+        return
+
+    # 2. Locate guidelines rules file
+    rules_file = Path(".agents/rules/documentation-rules.md")
+    rules_content = ""
+    if rules_file.exists():
+        try:
+            rules_content = rules_file.read_text(encoding="utf-8")
+        except Exception:
+            pass
+    if not rules_content:
+        rules_content = "# Guidelines\n* Use single standard H1 title.\n* Wrap Mermaid special labels in quotes.\n* Always fence code blocks with languages."
+
+    docs_dir = Path(config.documentation.docs_dir)
+    synced_any = False
+
+    for change in all_changes:
+        # We only sync context for modified or added files
+        if change.change_type not in ["M", "A"]:
+            continue
+
+        # AST analysis
+        try:
+            analysis = build_impact_analysis(change.filepath, change.diff)
+        except Exception as e:
+            console.print(f"[yellow]⚠️ Skipped AST parsing for {change.filepath}: {e}[/yellow]")
+            continue
+
+        # Find associated markdown files
+        associated = find_associated_docs(change.filepath, docs_dir)
+        if not associated:
+            continue
+
+        for md_path in associated:
+            synced_any = True
+            console.print(f"[bold cyan]🔗 Found associated documentation: {md_path}[/bold cyan]")
+            
+            try:
+                md_content = md_path.read_text(encoding="utf-8")
+            except Exception as e:
+                console.print(f"[red]❌ Failed to read {md_path}: {e}[/red]")
+                continue
+
+            # Build prompt
+            prompt = build_orchestrator_prompt(
+                rules_content=rules_content,
+                md_content=md_content,
+                md_filename=md_path.name,
+                analysis=analysis
+            )
+
+            if dry_run:
+                # Pretty print prompt
+                console.print(Panel(prompt, title=f"📋 Dry-Run AI Prompt for {md_path.name}", border_style="yellow"))
+                console.print(f"[bold yellow]⚠️ Dry-run: skipped API call for {md_path.name}[/bold yellow]\n")
+                continue
+
+            # Call AI
+            provider_label = config.ai.provider.upper()
+            with console.status(f"[bold green]Running AI Sync ({provider_label}) for {md_path.name}...") as status:
+                updated_content, err = execute_llm_update(config, prompt)
+
+            if err:
+                console.print(f"[bold red]❌ AI Sync Failed: {err}[/bold red]")
+                console.print(f"[yellow]💡 Tip: Set the environment variable {provider_label}_API_KEY or run with --dry-run[/yellow]\n")
+                continue
+
+            if not updated_content:
+                console.print(f"[bold red]❌ AI returned empty response for {md_path.name}[/bold red]\n")
+                continue
+
+            # Validate generated markdown before saving
+            issues = check_markdown_content(updated_content)
+            if issues:
+                console.print(f"[bold yellow]⚠️ Warning: AI output for {md_path.name} violated styling rules:[/bold yellow]")
+                for issue in issues:
+                    console.print(f"  - [yellow]{issue}[/yellow]")
+                console.print("[bold yellow]Proceeding to save with warnings...[/bold yellow]")
+
+            # Save the file
+            try:
+                md_path.write_text(updated_content, encoding="utf-8")
+                console.print(f"[bold green]✅ Successfully updated technical documentation: {md_path}[/bold green]\n")
+            except Exception as e:
+                console.print(f"[bold red]❌ Failed to save changes to {md_path}: {e}[/bold red]\n")
+
+    if not synced_any:
+        console.print("[bold yellow]⚠️ No associated documentation files were found in the docs directory for the changed files.[/bold yellow]")
+        console.print(f"[dim]Note: Documentation is matched if the file name stem or classes are mentioned in the markdown file.[/dim]")
+
+@app.command("view")
+def view_cmd(
+    filepath: Path = typer.Argument(
+        ...,
+        help="Path to the technical markdown (.md) document to view."
+    )
+):
+    """
+    Render a technical documentation markdown file directly inside the terminal with beautiful, rich formatting.
+    """
+    if not filepath.exists():
+        console.print(f"[bold red]❌ Error: File '{filepath}' does not exist.[/bold red]")
+        raise typer.Exit(code=1)
+        
+    try:
+        content = filepath.read_text(encoding="utf-8")
+        md = Markdown(content)
+        console.print(md)
+    except Exception as e:
+        console.print(f"[bold red]❌ Error reading or rendering file: {e}[/bold red]")
+        raise typer.Exit(code=1)
+
+if __name__ == "__main__":
+    app()

docuflow/parser.py

@@ -0,0 +1,105 @@
+import ast
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+class ParameterInfo(BaseModel):
+    """
+    Represents metadata for a function or method parameter.
+    """
+    name: str
+    type_annotation: Optional[str] = None
+
+class EntityInfo(BaseModel):
+    """
+    Represents a structural code entity (class, function, or method).
+    """
+    name: str
+    type: str  # "class", "function", "method"
+    signature: str
+    docstring: Optional[str] = None
+    line_start: int
+    line_end: int
+    parameters: List[ParameterInfo] = Field(default_factory=list)
+    return_type: Optional[str] = None
+
+class PythonASTVisitor(ast.NodeVisitor):
+    """
+    AST Visitor to traverse and extract high-level structural classes and functions.
+    """
+    def __init__(self):
+        self.entities: List[EntityInfo] = []
+        self.current_class: Optional[str] = None
+
+    def visit_ClassDef(self, node: ast.ClassDef):
+        docstring = ast.get_docstring(node)
+        # Class bases / inheritance
+        bases = [ast.unparse(b) for b in node.bases]
+        bases_str = f"({', '.join(bases)})" if bases else ""
+        signature = f"class {node.name}{bases_str}"
+        
+        self.entities.append(EntityInfo(
+            name=node.name,
+            type="class",
+            signature=signature,
+            docstring=docstring,
+            line_start=node.lineno,
+            line_end=getattr(node, "end_lineno", node.lineno),
+        ))
+        
+        # Save context to visit methods inside this class
+        old_class = self.current_class
+        self.current_class = node.name
+        self.generic_visit(node)
+        self.current_class = old_class
+
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        self.visit_any_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef):
+        self.visit_any_function(node)
+
+    def visit_any_function(self, node):
+        docstring = ast.get_docstring(node)
+        
+        # Extract parameter details
+        params = []
+        for arg in node.args.args:
+            annotation = ast.unparse(arg.annotation) if arg.annotation else None
+            params.append(ParameterInfo(name=arg.arg, type_annotation=annotation))
+            
+        return_type = ast.unparse(node.returns) if node.returns else None
+        prefix = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
+        func_type = "method" if self.current_class else "function"
+        
+        # Format human-readable signature
+        args_str = ", ".join([p.name + (f": {p.type_annotation}" if p.type_annotation else "") for p in params])
+        signature = f"{prefix} {node.name}({args_str})"
+        if return_type:
+            signature += f" -> {return_type}"
+            
+        self.entities.append(EntityInfo(
+            name=f"{self.current_class}.{node.name}" if self.current_class else node.name,
+            type=func_type,
+            signature=signature,
+            docstring=docstring,
+            line_start=node.lineno,
+            line_end=getattr(node, "end_lineno", node.lineno),
+            parameters=params,
+            return_type=return_type
+        ))
+        
+        # Keep walking to capture nested structures if any
+        self.generic_visit(node)
+
+def parse_code_structure(code: str) -> List[EntityInfo]:
+    """
+    Parses a string of Python code and returns a list of high-level code entities.
+    Returns an empty list if compilation fails (e.g., SyntaxError).
+    """
+    try:
+        tree = ast.parse(code)
+        visitor = PythonASTVisitor()
+        visitor.visit(tree)
+        return visitor.entities
+    except (SyntaxError, ValueError, TypeError):
+        return []

docuflow-0.3.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+docuflow/__init__.py,sha256=2T9r9Wswt_-AoPkH5ZJMOYhEXjeRaAB8JtzVR9JB6Xg,98
+docuflow/ai_engine.py,sha256=Q0JGiWu-8otW9Nb-59HJbJ4-zuRb6kgjokBx_JJVd_0,7215
+docuflow/config.py,sha256=luJYZmd9OTwrv-V-mBpYPUni_tpt5DjqPLgOTmLNvb0,1948
+docuflow/context_builder.py,sha256=T9NdO51I4meEIX91O6gmQ0silvVu7fe8AU2phsX9Has,3345
+docuflow/git_utils.py,sha256=Cxo22N0x5uRCTIH_789mdZyPX8pc6MeY5UGL6qu7t3o,6189
+docuflow/main.py,sha256=J-i64DiDFlZFD5K1ro1tztiUTJrs_DKiQCBmr3wGa6s,20395
+docuflow/parser.py,sha256=Lf9EueeYsxitUFfPJknrHx9kWhRAkUM9oGBzdLVt62Y,3698
+docuflow-0.3.0.dist-info/METADATA,sha256=Vs6QTtNqEv6bd5UgkhMN9tlEM-qUERB5Ep5ziR4naxU,586
+docuflow-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+docuflow-0.3.0.dist-info/entry_points.txt,sha256=LmScDeRtkjbJwiQ8ig1TSqUUlOmHY_vGBEnYOPECeLo,47
+docuflow-0.3.0.dist-info/top_level.txt,sha256=kvU6iukZnp5Vw_NOn_71vEzGc9lvEkpBp5DlJcRrOGA,9
+docuflow-0.3.0.dist-info/RECORD,,

docuflow-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

docuflow-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docuflow = docuflow.main:app

docuflow-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+docuflow