devobin 1.0.0__py3-none-any.whl

devobin/core/prompt_builder.py

@@ -0,0 +1,513 @@
+"""Prompt compiler — generates production-ready engineering instruction files."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from devobin.core.analyzer import AnalysisResult
+from devobin.core.researcher import ResearchTopic
+
+
+@dataclass
+class PromptSection:
+    """A section of the compiled prompt."""
+
+    title: str
+    level: int = 2
+    content: list[str] = field(default_factory=list)
+
+
+def _tech_list(names: list[str]) -> str:
+    return ", ".join(f"`{n}`" for n in names) if names else "Not specified"
+
+
+def _generate_filename(analysis: AnalysisResult, project_name: str | None = None) -> str:
+    """Generate a clean filename from the analysis or project name."""
+    if project_name:
+        slug = project_name.lower().strip()
+        slug = slug.replace(" ", "_").replace("-", "_")
+        slug = "".join(c for c in slug if c.isalnum() or c == "_")
+        return f"{slug}_prompt.md"
+
+    # Auto-generate from detected technologies
+    parts = []
+    for tech in analysis.detected_techs[:3]:
+        name = tech.name.lower().replace(" ", "_").replace(".", "")
+        parts.append(name)
+
+    if analysis.project_type and analysis.project_type != "general":
+        parts.append(analysis.project_type.replace(" ", "_"))
+
+    if parts:
+        return "_".join(parts) + "_prompt.md"
+
+    return "project_prompt.md"
+
+
+def build_prompt(
+    analysis: AnalysisResult,
+    research: dict[str, ResearchTopic],
+    user_context: str = "",
+    memory_context: str = "",
+    project_name: str | None = None,
+    project_map=None,
+) -> tuple[str, str]:
+    """Build the complete engineering instruction file.
+
+    Returns:
+        (filename, content) tuple
+    """
+    sections: list[PromptSection] = []
+
+    # ── Header ────────────────────────────────────────────────────
+    sections.append(PromptSection("DevObin Engineering Instructions", level=1, content=[
+        "> Auto-generated by DevObin AI — Prompt Enhancement Layer",
+        f"> Project type: **{analysis.project_type or 'General Application'}**",
+        "",
+    ]))
+
+    # ── Detected Workspace (from real file scan) ──────────────────
+    if project_map is not None and getattr(project_map, "total_files", 0):
+        sections.append(PromptSection("Detected Workspace", level=2, content=[
+            project_map.to_context(max_chars=6000),
+            "",
+        ]))
+
+    # ── Role ──────────────────────────────────────────────────────
+    role_lines = _determine_role(analysis)
+    sections.append(PromptSection("Role", level=2, content=role_lines + [""]))
+
+    # ── Project Goal ──────────────────────────────────────────────
+    goal_lines = _determine_goal(analysis)
+    sections.append(PromptSection("Project Goal", level=2, content=goal_lines + [""]))
+
+    # ── Technology Stack ──────────────────────────────────────────
+    stack_lines = []
+    categories = {}
+    for tech in analysis.detected_techs:
+        categories.setdefault(tech.category, []).append(tech.name)
+
+    cat_labels = {
+        "framework": "Backend Framework",
+        "frontend": "Frontend",
+        "database": "Database",
+        "language": "Language",
+        "tool": "Tool",
+        "cloud": "Cloud",
+        "pattern": "Pattern",
+        "domain": "Domain",
+    }
+
+    for cat, names in categories.items():
+        stack_lines.append(f"- **{cat_labels.get(cat, cat.title())}**: {_tech_list(names)}")
+
+    if not stack_lines:
+        stack_lines = ["- Not explicitly specified — use your best judgment based on the project description."]
+
+    sections.append(PromptSection("Technology Stack", level=2, content=stack_lines + [""]))
+
+    # ── Technical Constraints ─────────────────────────────────────
+    constraints = _determine_constraints(analysis)
+    sections.append(PromptSection("Technical Constraints", level=2, content=constraints + [""]))
+
+    # ── Required Sections / Features ──────────────────────────────
+    features = _determine_features(analysis)
+    sections.append(PromptSection("Required Sections", level=2, content=features + [""]))
+
+    # ── Implementation Details ────────────────────────────────────
+    impl_details = _determine_implementation(analysis, research)
+    sections.append(PromptSection("Implementation Details", level=2, content=impl_details + [""]))
+
+    # ── Architecture Rules ────────────────────────────────────────
+    arch_rules = [
+        "Follow SOLID principles throughout the codebase",
+        "Apply Clean Architecture: separate concerns into layers",
+        "Use dependency injection for loose coupling",
+        "Keep functions focused — single responsibility",
+        "Design for testability from the start",
+        "Use meaningful naming conventions",
+        "Write self-documenting code; avoid unnecessary comments",
+    ]
+
+    for name, topic in research.items():
+        if topic.architecture_rules:
+            arch_rules.append(f"\n**{name} Architecture:**")
+            arch_rules.extend([f"- {r}" for r in topic.architecture_rules])
+
+    sections.append(PromptSection("Architecture Rules", level=2, content=arch_rules + [""]))
+
+    # ── Responsive Design (only if project has a UI) ───────────────
+    has_ui = any(t.category in ("frontend",) for t in analysis.detected_techs)
+    if has_ui:
+        responsive = _determine_responsive(analysis)
+        sections.append(PromptSection("Responsive Design", level=2, content=responsive + [""]))
+
+    # ── UI/UX Quality (only if project has a UI) ──────────────────
+    if has_ui:
+        ui_rules = _determine_ui_quality(analysis)
+        sections.append(PromptSection("UI/UX Quality", level=2, content=ui_rules + [""]))
+
+    # ── Framework Best Practices ──────────────────────────────────
+    framework_rules: list[str] = []
+    for name, topic in research.items():
+        if topic.best_practices:
+            framework_rules.append(f"### {name}")
+            framework_rules.extend([f"- {bp}" for bp in topic.best_practices])
+            framework_rules.append("")
+
+    if framework_rules:
+        sections.append(PromptSection("Framework Best Practices", level=2, content=framework_rules + [""]))
+
+    # ── Security Rules ────────────────────────────────────────────
+    security_rules = [
+        "Validate and sanitize ALL user inputs at system boundaries",
+        "Use parameterized queries — never concatenate user input into queries",
+        "Implement proper authentication and authorization checks on every endpoint",
+        "Use HTTPS everywhere in production",
+        "Store secrets in environment variables, never in code or version control",
+        "Implement rate limiting on public endpoints",
+        "Use Content Security Policy (CSP) headers",
+        "Log security events for audit trails",
+    ]
+
+    for name, topic in research.items():
+        if topic.security_rules:
+            security_rules.append(f"\n**{name} Security:**")
+            security_rules.extend([f"- {r}" for r in topic.security_rules])
+
+    sections.append(PromptSection("Security Rules", level=2, content=security_rules + [""]))
+
+    # ── Performance Rules ─────────────────────────────────────────
+    perf_rules = [
+        "Profile before optimizing — measure, don't guess",
+        "Implement caching at appropriate layers",
+        "Use async/concurrent processing for I/O-bound operations",
+        "Paginate all list endpoints",
+        "Optimize database queries — avoid N+1",
+        "Implement proper logging and monitoring",
+        "Design for horizontal scalability",
+    ]
+
+    for name, topic in research.items():
+        if topic.performance_tips:
+            perf_rules.append(f"\n**{name} Performance:**")
+            perf_rules.extend([f"- {t}" for t in topic.performance_tips])
+
+    sections.append(PromptSection("Performance Rules", level=2, content=perf_rules + [""]))
+
+    # ── Common Mistakes ───────────────────────────────────────────
+    mistakes: list[str] = []
+    for name, topic in research.items():
+        if topic.common_mistakes:
+            mistakes.append(f"**{name}:**")
+            mistakes.extend([f"- Avoid: {m}" for m in topic.common_mistakes])
+            mistakes.append("")
+
+    if mistakes:
+        sections.append(PromptSection("Common Mistakes to Avoid", level=2, content=mistakes + [""]))
+
+    # ── Development Workflow ──────────────────────────────────────
+    workflow = [
+        "1. **Analyze requirements** — break down into concrete deliverables",
+        "2. **Design architecture** — propose system design before coding",
+        "3. **Explain decisions** — justify architectural choices with trade-offs",
+        "4. **Create implementation plan** — break work into small, testable units",
+        "5. **Implement step by step** — build incrementally with tests",
+        "6. **Test thoroughly** — write unit, integration, and edge-case tests",
+        "7. **Optimize** — profile and optimize critical paths only when needed",
+        "8. **Document** — add API docs and deployment instructions",
+    ]
+    sections.append(PromptSection("Development Workflow", level=2, content=workflow + [""]))
+
+    # ── User Context / Memory ─────────────────────────────────────
+    if memory_context:
+        sections.append(PromptSection("User Preferences (from DevObin Memory)", level=2, content=[
+            memory_context,
+            "",
+        ]))
+
+    if user_context:
+        sections.append(PromptSection("Additional Context", level=2, content=[
+            user_context,
+            "",
+        ]))
+
+    # ── Assemble ──────────────────────────────────────────────────
+    lines: list[str] = []
+    for section in sections:
+        if section.level == 1:
+            lines.append(f"# {section.title}")
+        else:
+            lines.append(f"{'#' * section.level} {section.title}")
+        lines.extend(section.content)
+
+    filename = _generate_filename(analysis, project_name)
+    return filename, "\n".join(lines)
+
+
+# ── Section generators ────────────────────────────────────────────
+
+
+def _determine_role(analysis: AnalysisResult) -> list[str]:
+    """Determine the appropriate role based on detected tech."""
+    categories = {t.category for t in analysis.detected_techs}
+
+    if "frontend" in categories and "framework" not in categories:
+        return [
+            "You are a senior frontend engineer specialized in modern web interfaces.",
+            "Your implementation must be pixel-perfect, responsive, and follow accessibility standards.",
+        ]
+    if "frontend" in categories and "framework" in categories:
+        return [
+            "You are a senior full-stack engineer specialized in modern web applications.",
+            "Your implementation must be production-ready, well-tested, and follow industry best practices.",
+        ]
+    if "framework" in categories:
+        return [
+            "You are a senior backend architect specialized in API design and server-side engineering.",
+            "Your implementation must be scalable, secure, and follow clean architecture principles.",
+        ]
+    if analysis.project_type in ("saas",):
+        return [
+            "You are a senior SaaS architect specialized in multi-tenant applications.",
+            "Your implementation must handle scaling, security, and tenant isolation.",
+        ]
+
+    return [
+        "You are a senior software architect and production engineer.",
+        "Your implementation must be production-ready, well-tested, and follow industry best practices.",
+    ]
+
+
+def _determine_goal(analysis: AnalysisResult) -> list[str]:
+    """Determine the project goal from analysis."""
+    lines = [f"Build: {analysis.description}", ""]
+
+    if analysis.project_type and analysis.project_type != "general":
+        lines.append(f"Project type: **{analysis.project_type}**")
+
+    if analysis.detected_techs:
+        tech_names = [t.name for t in analysis.detected_techs]
+        lines.append(f"Technologies: {', '.join(tech_names)}")
+
+    return lines
+
+
+def _determine_constraints(analysis: AnalysisResult) -> list[str]:
+    """Determine technical constraints from analysis."""
+    constraints = []
+    has_ui = any(t.category in ("frontend",) for t in analysis.detected_techs)
+
+    # Check for single-file mentions
+    desc_lower = analysis.description.lower()
+    if any(phrase in desc_lower for phrase in ["one file", "single file", "یک فایل", "یه فایل", "mega file", "همه چی"]):
+        constraints.append("- The entire project must exist in ONE file")
+        constraints.append("- Include HTML, CSS, and JavaScript in the same file")
+        constraints.append("- No external frameworks or dependencies")
+
+    if "no framework" in desc_lower or "vanilla" in desc_lower:
+        constraints.append("- Use vanilla JavaScript only — no frameworks")
+        constraints.append("- No external dependencies")
+
+    if analysis.project_type == "ecommerce":
+        constraints.append("- Must handle product data (can use mock/placeholder data)")
+        constraints.append("- Cart state must persist (use localStorage)")
+
+    if not constraints:
+        constraints.append("- Follow standard project structure for the detected technologies")
+        if has_ui:
+            constraints.append("- Use modern ES6+ features where supported")
+        else:
+            constraints.append("- Use idiomatic patterns for the detected language")
+            constraints.append("- Follow PEP 8 / official style guide for the language")
+
+    return constraints
+
+
+def _determine_features(analysis: AnalysisResult) -> list[str]:
+    """Determine required features/sections from analysis."""
+    features = []
+    desc_lower = analysis.description.lower()
+
+    # Ecommerce features
+    if analysis.project_type == "ecommerce" or "shop" in desc_lower or "store" in desc_lower or "فروشگاه" in desc_lower:
+        features.extend([
+            "**Header** — Logo, navigation, search bar, cart icon with counter",
+            "**Mega Menu** — Multi-column dropdown with categories, subcategories, icons/images",
+            "**Hero Section** — Banner with CTA button",
+            "**Product Grid/Slider** — Product cards with image, title, price, add-to-cart",
+            "**Shopping Cart** — Slide-out or modal cart with items, quantities, total",
+            "**Categories Section** — Category cards with icons",
+            "**Footer** — Links, social media, newsletter signup",
+        ])
+
+    # Blog features
+    if "blog" in desc_lower or "وبلاگ" in desc_lower:
+        features.extend([
+            "**Header** — Logo, navigation, search",
+            "**Featured Posts** — Hero cards with images",
+            "**Post List** — Card grid with title, excerpt, date, author",
+            "**Sidebar** — Categories, tags, popular posts",
+            "**Post Detail** — Full article with rich content",
+            "**Footer** — Links, social, about",
+        ])
+
+    # Dashboard features
+    if "dashboard" in desc_lower or "پنل" in desc_lower:
+        features.extend([
+            "**Sidebar Navigation** — Collapsible menu with icons",
+            "**Top Bar** — Search, notifications, user profile",
+            "**Stats Cards** — KPIs with charts",
+            "**Data Table** — Sortable, filterable, paginated",
+            "**Charts** — Line, bar, pie charts for analytics",
+        ])
+
+    # Landing page
+    if "landing" in desc_lower or "لندینگ" in desc_lower:
+        features.extend([
+            "**Hero Section** — Headline, subheadline, CTA",
+            "**Features Section** — 3-4 feature cards with icons",
+            "**Social Proof** — Testimonials or logos",
+            "**Pricing** — Pricing tiers with CTA buttons",
+            "**FAQ** — Accordion-style FAQ section",
+            "**Footer** — Links, newsletter signup",
+        ])
+
+    if not features:
+        # Only add frontend features if the project actually has a UI component
+        has_ui = any(t.category in ("frontend",) for t in analysis.detected_techs)
+        if has_ui:
+            features.append("- Define required UI sections based on project type")
+            features.append("- Include header, main content area, and footer at minimum")
+        else:
+            features.append("- Define required modules/components based on the detected stack")
+            features.append("- List all API endpoints, CLI commands, or library interfaces to implement")
+            features.append("- Specify data models, schemas, or type definitions needed")
+
+    return features
+
+
+def _determine_implementation(analysis: AnalysisResult, research: dict[str, ResearchTopic]) -> list[str]:
+    """Determine implementation details."""
+    details = []
+    desc_lower = analysis.description.lower()
+    has_ui = any(t.category in ("frontend",) for t in analysis.detected_techs)
+
+    if any(phrase in desc_lower for phrase in ["mega menu", "مگا منو", "menu", "منو"]):
+        details.extend([
+            "**Mega Menu:**",
+            "- Multi-column dropdown layout",
+            "- Product categories with subcategories",
+            "- Icons or thumbnail images per category",
+            "- Desktop: hover to open, with transition animation",
+            "- Mobile: tap to toggle, full-width overlay",
+            "- Smooth open/close animations (CSS transitions)",
+        ])
+
+    if analysis.project_type == "ecommerce" or "shop" in desc_lower or "فروشگاه" in desc_lower:
+        details.extend([
+            "**Product Slider:**",
+            "- Horizontal scrolling product carousel",
+            "- Arrow navigation (prev/next)",
+            "- Dot indicators",
+            "- Auto-play with pause on hover",
+            "",
+            "**Shopping Cart:**",
+            "- Slide-out panel or modal",
+            "- Add/remove items",
+            "- Quantity +/- controls",
+            "- Live total calculation",
+            "- localStorage persistence",
+            "- Empty cart state",
+            "",
+            "**Mobile Menu:**",
+            "- Hamburger icon toggle",
+            "- Full-screen overlay menu",
+            "- Nested category accordion",
+            "- Close button + swipe gesture",
+        ])
+
+    if not details:
+        if has_ui:
+            details.append("- Implement all interactive features with clean JavaScript")
+            details.append("- Use event delegation for dynamic elements")
+            details.append("- Handle loading, empty, and error states")
+        else:
+            details.append("- Implement core business logic with clean, well-structured code")
+            details.append("- Use type hints and docstrings for all public interfaces")
+            details.append("- Handle error states and edge cases gracefully")
+            details.append("- Write unit tests for core functionality")
+
+    return details
+
+
+def _determine_responsive(analysis: AnalysisResult) -> list[str]:
+    """Determine responsive design requirements."""
+    return [
+        "**Breakpoints:**",
+        "- Desktop: > 1024px",
+        "- Tablet: 768px - 1024px",
+        "- Mobile: < 768px",
+        "",
+        "**Desktop:**",
+        "- Full mega menu with hover interaction",
+        "- Multi-column product grid (3-4 columns)",
+        "- Sticky header",
+        "",
+        "**Tablet:**",
+        "- Condensed navigation",
+        "- 2-column product grid",
+        "- Adjusted typography scale",
+        "",
+        "**Mobile:**",
+        "- Hamburger menu with full-screen overlay",
+        "- Single-column layout",
+        "- Touch-friendly tap targets (min 44px)",
+        "- Swipe gestures for carousels",
+        "- Bottom navigation bar (optional)",
+    ]
+
+
+def _determine_ui_quality(analysis: AnalysisResult) -> list[str]:
+    """Determine UI/UX quality requirements."""
+    desc_lower = analysis.description.lower()
+
+    rules = [
+        "**Design Style:**",
+        "- Modern, clean, professional ecommerce design",
+        "- Consistent spacing system (8px grid)",
+        "- Clear visual hierarchy",
+        "",
+        "**Typography:**",
+        "- Use system font stack or Google Fonts",
+        "- Maximum 2-3 font weights",
+        "- Readable line height (1.5-1.6)",
+        "- Responsive font sizes (clamp or media queries)",
+        "",
+        "**Colors:**",
+        "- Define primary, secondary, and accent colors",
+        "- Ensure WCAG AA contrast ratios",
+        "- Use CSS custom properties for theming",
+        "",
+        "**Spacing:**",
+        "- Consistent padding/margin scale",
+        "- Visual breathing room between sections",
+        "",
+        "**Animations:**",
+        "- Smooth transitions (200-300ms ease)",
+        "- Hover effects on interactive elements",
+        "- Loading skeleton states",
+        "- Subtle micro-interactions",
+    ]
+
+    if "rtl" in desc_lower or "فارسی" in desc_lower or "persian" in desc_lower:
+        rules.extend([
+            "",
+            "**RTL Support:**",
+            "- Use dir='rtl' on html element",
+            "- Logical properties (margin-inline, padding-inline)",
+            "- Mirrored layout for RTL languages",
+            "- Proper text alignment",
+        ])
+
+    return rules