mobile-best-practices 1.0.0

package/assets/scripts/core.py

@@ -0,0 +1,432 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Mobile Best Practices Core - BM25 search engine for mobile development best practices
+"""
+
+import csv
+import json
+import re
+from pathlib import Path
+from math import log
+from collections import defaultdict
+from datetime import datetime
+
+# ============ CONFIGURATION ============
+DATA_DIR = Path(__file__).parent.parent / "data"
+MAX_RESULTS = 3
+
+CSV_CONFIG = {
+    "architecture": {
+        "file": "architectures.csv",
+        "search_cols": ["Name", "Platform", "Keywords", "Best For", "Tech Stack"],
+        "output_cols": ["Name", "Platform", "Complexity", "Team Size", "Keywords", "Best For", "Tech Stack", "Layers", "Structure", "Anti Patterns", "Notes"]
+    },
+    "ui": {
+        "file": "ui-patterns.csv",
+        "search_cols": ["Pattern Name", "Platform", "Category", "Keywords", "Use Case"],
+        "output_cols": ["Pattern Name", "Platform", "Category", "Keywords", "Use Case", "Components", "Implementation Notes", "Accessibility"]
+    },
+    "template": {
+        "file": "project-templates.csv",
+        "search_cols": ["Template Name", "Platform", "Architecture", "Tech Stack", "Features Included"],
+        "output_cols": ["Template Name", "Platform", "Architecture", "Tech Stack", "Modules", "Folder Structure", "Features Included", "Key Dependencies"]
+    },
+    "antipattern": {
+        "file": "anti-patterns.csv",
+        "search_cols": ["Name", "Platform", "Category", "Keywords", "Description"],
+        "output_cols": ["Name", "Platform", "Category", "Severity", "Description", "Bad Example", "Good Example", "Why Bad", "Fix"]
+    },
+    "reasoning": {
+        "file": "reasoning-rules.csv",
+        "search_cols": ["Product Type", "Platform", "Keywords", "Key Features"],
+        "output_cols": ["Product Type", "Platform", "Recommended Arch", "Recommended UI", "Color Mood", "Key Features", "Anti Patterns", "Key Dependencies", "Notes"]
+    },
+    "library": {
+        "file": "libraries.csv",
+        "search_cols": ["Name", "Platform", "Category", "Keywords", "Description"],
+        "output_cols": ["Name", "Platform", "Category", "Keywords", "Description", "Gradle/Pod/Pub", "Alternative", "Stars", "Notes"]
+    },
+    "performance": {
+        "file": "performance.csv",
+        "search_cols": ["Category", "Issue", "Platform", "Keywords", "Description"],
+        "output_cols": ["Category", "Issue", "Platform", "Severity", "Description", "Do", "Dont", "Code Good", "Code Bad", "Metric"]
+    },
+    "testing": {
+        "file": "testing.csv",
+        "search_cols": ["Category", "Pattern", "Platform", "Keywords", "Description"],
+        "output_cols": ["Category", "Pattern", "Platform", "Description", "Framework", "Code Example", "Anti Pattern", "Notes"]
+    },
+    "security": {
+        "file": "security.csv",
+        "search_cols": ["Category", "Threat", "Platform", "Keywords", "Description"],
+        "output_cols": ["Category", "Threat", "Platform", "Severity", "Description", "Mitigation", "Code Good", "Code Bad", "OWASP Ref"]
+    },
+    "snippet": {
+        "file": "code-snippets.csv",
+        "search_cols": ["Name", "Category", "Keywords", "Description"],
+        "output_cols": ["ID", "Name", "Platform", "Category", "Description", "Code", "Imports", "Notes"]
+    },
+    "gradle": {
+        "file": "gradle-deps.csv",
+        "search_cols": ["Name", "Category", "Keywords"],
+        "output_cols": ["Name", "Category", "Version Catalog Key", "Implementation", "KSP/KAPT", "Version", "Notes"]
+    }
+}
+
+PLATFORM_CONFIG = {
+    "android": {"file": "platforms/android.csv"},
+    "ios": {"file": "platforms/ios.csv"},
+    "flutter": {"file": "platforms/flutter.csv"},
+    "react-native": {"file": "platforms/react-native.csv"}
+}
+
+_PLATFORM_COLS = {
+    "search_cols": ["Category", "Guideline", "Description", "Do", "Dont"],
+    "output_cols": ["Category", "Guideline", "Description", "Do", "Dont", "Code Good", "Code Bad", "Severity", "Docs URL"]
+}
+
+AVAILABLE_PLATFORMS = list(PLATFORM_CONFIG.keys())
+
+# Stack-to-platform mapping for --stack search
+STACK_MAP = {
+    "compose": "android",
+    "jetpack-compose": "android",
+    "material3": "android",
+    "hilt": "android",
+    "room": "android",
+    "kotlin": "android",
+    "swiftui": "ios",
+    "combine": "ios",
+    "uikit": "ios",
+    "swift": "ios",
+    "flutter": "flutter",
+    "dart": "flutter",
+    "bloc": "flutter",
+    "riverpod": "flutter",
+    "react-native": "react-native",
+    "rn": "react-native",
+    "hooks": "react-native",
+    "typescript": "react-native",
+    "redux": "react-native",
+}
+
+AVAILABLE_STACKS = list(STACK_MAP.keys())
+
+
+# ============ BM25 IMPLEMENTATION ============
+class BM25:
+    """BM25 ranking algorithm for text search"""
+
+    def __init__(self, k1=1.5, b=0.75):
+        self.k1 = k1
+        self.b = b
+        self.corpus = []
+        self.doc_lengths = []
+        self.avgdl = 0
+        self.idf = {}
+        self.doc_freqs = defaultdict(int)
+        self.N = 0
+
+    def tokenize(self, text):
+        """Lowercase, split, remove punctuation, filter short words"""
+        text = re.sub(r'[^\w\s]', ' ', str(text).lower())
+        return [w for w in text.split() if len(w) > 2]
+
+    def fit(self, documents):
+        """Build BM25 index from documents"""
+        self.corpus = [self.tokenize(doc) for doc in documents]
+        self.N = len(self.corpus)
+        if self.N == 0:
+            return
+        self.doc_lengths = [len(doc) for doc in self.corpus]
+        self.avgdl = sum(self.doc_lengths) / self.N
+
+        for doc in self.corpus:
+            seen = set()
+            for word in doc:
+                if word not in seen:
+                    self.doc_freqs[word] += 1
+                    seen.add(word)
+
+        for word, freq in self.doc_freqs.items():
+            self.idf[word] = log((self.N - freq + 0.5) / (freq + 0.5) + 1)
+
+    def score(self, query):
+        """Score all documents against query"""
+        query_tokens = self.tokenize(query)
+        scores = []
+
+        for idx, doc in enumerate(self.corpus):
+            score = 0
+            doc_len = self.doc_lengths[idx]
+            term_freqs = defaultdict(int)
+            for word in doc:
+                term_freqs[word] += 1
+
+            for token in query_tokens:
+                if token in self.idf:
+                    tf = term_freqs[token]
+                    idf = self.idf[token]
+                    numerator = tf * (self.k1 + 1)
+                    denominator = tf + self.k1 * (1 - self.b + self.b * doc_len / self.avgdl)
+                    score += idf * numerator / denominator
+
+            scores.append((idx, score))
+
+        return sorted(scores, key=lambda x: x[1], reverse=True)
+
+
+# ============ SEARCH FUNCTIONS ============
+def _load_csv(filepath):
+    """Load CSV and return list of dicts"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        return list(csv.DictReader(f))
+
+
+def _search_csv(filepath, search_cols, output_cols, query, max_results):
+    """Core search function using BM25"""
+    if not filepath.exists():
+        return []
+
+    data = _load_csv(filepath)
+
+    # Build documents from search columns
+    documents = [" ".join(str(row.get(col, "")) for col in search_cols) for row in data]
+
+    # BM25 search
+    bm25 = BM25()
+    bm25.fit(documents)
+    ranked = bm25.score(query)
+
+    # Get top results with score > 0
+    results = []
+    for idx, score in ranked[:max_results]:
+        if score > 0:
+            row = data[idx]
+            results.append({col: row.get(col, "") for col in output_cols if col in row})
+
+    return results
+
+
+def detect_domain(query):
+    """Auto-detect the most relevant domain from query"""
+    query_lower = query.lower()
+
+    domain_keywords = {
+        "architecture": ["mvvm", "mvi", "viper", "bloc", "clean", "architecture", "repository", "coordinator", "redux", "tca", "layer", "module"],
+        "ui": ["button", "navigation", "bottom sheet", "tab", "list", "card", "dialog", "modal", "drawer", "scaffold", "appbar", "toolbar"],
+        "template": ["project", "template", "setup", "scaffold", "starter", "boilerplate", "create", "new app", "init"],
+        "antipattern": ["anti-pattern", "antipattern", "mistake", "bad practice", "wrong", "avoid", "smell", "god class", "leak"],
+        "reasoning": ["ecommerce", "e-commerce", "banking", "fintech", "social", "healthcare", "delivery", "fitness", "education", "food", "chat", "streaming"],
+        "library": ["library", "dependency", "package", "retrofit", "hilt", "room", "coil", "ktor", "alamofire", "dio", "riverpod", "redux"],
+        "performance": ["performance", "memory", "battery", "startup", "render", "fps", "lag", "slow", "optimize", "profil", "baseline"],
+        "testing": ["test", "unit test", "ui test", "espresso", "xctest", "mockito", "junit", "widget test", "integration"],
+        "security": ["security", "encrypt", "keychain", "keystore", "proguard", "obfuscate", "ssl", "pin", "biometric", "auth token"],
+        "snippet": ["snippet", "code", "example", "template code", "viewmodel code", "compose screen", "room setup", "hilt module", "bottom nav", "paging", "datastore", "theme code"],
+        "gradle": ["gradle", "dependency", "implementation", "ksp", "kapt", "version catalog", "libs.", "bom", "plugin", "classpath"]
+    }
+
+    scores = {domain: sum(1 for kw in keywords if kw in query_lower) for domain, keywords in domain_keywords.items()}
+    best = max(scores, key=scores.get)
+    return best if scores[best] > 0 else "architecture"
+
+
+def search(query, domain=None, max_results=MAX_RESULTS, filter_platform=None):
+    """Main search function with auto-domain detection and optional platform filter"""
+    if domain is None:
+        domain = detect_domain(query)
+
+    config = CSV_CONFIG.get(domain, CSV_CONFIG["architecture"])
+    filepath = DATA_DIR / config["file"]
+
+    if not filepath.exists():
+        return {"error": f"File not found: {filepath}", "domain": domain}
+
+    results = _search_csv(filepath, config["search_cols"], config["output_cols"], query, max_results * 3 if filter_platform else max_results)
+
+    # Filter by platform if specified
+    if filter_platform and results:
+        filter_lower = filter_platform.lower()
+        results = [r for r in results if any(
+            filter_lower in str(v).lower()
+            for k, v in r.items()
+            if k.lower() == "platform"
+        )][:max_results]
+
+    return {
+        "domain": domain,
+        "query": query,
+        "file": config["file"],
+        "count": len(results),
+        "results": results
+    }
+
+
+def search_platform(query, platform, max_results=MAX_RESULTS):
+    """Search platform-specific guidelines"""
+    if platform not in PLATFORM_CONFIG:
+        return {"error": f"Unknown platform: {platform}. Available: {', '.join(AVAILABLE_PLATFORMS)}"}
+
+    filepath = DATA_DIR / PLATFORM_CONFIG[platform]["file"]
+
+    if not filepath.exists():
+        return {"error": f"Platform file not found: {filepath}", "platform": platform}
+
+    results = _search_csv(filepath, _PLATFORM_COLS["search_cols"], _PLATFORM_COLS["output_cols"], query, max_results)
+
+    return {
+        "domain": "platform",
+        "platform": platform,
+        "query": query,
+        "file": PLATFORM_CONFIG[platform]["file"],
+        "count": len(results),
+        "results": results
+    }
+
+
+def search_stack(query, stack, max_results=MAX_RESULTS):
+    """Search filtered by tech stack (maps stack to platform + adds stack keywords)"""
+    stack_lower = stack.lower()
+
+    if stack_lower not in STACK_MAP:
+        return {"error": f"Unknown stack: {stack}. Available: {', '.join(AVAILABLE_STACKS)}"}
+
+    platform = STACK_MAP[stack_lower]
+
+    # Search platform guidelines first
+    platform_results = search_platform(f"{query} {stack}", platform, max_results)
+
+    # Also search across domains filtered by platform
+    domain_results = search(f"{query} {stack}", filter_platform=platform, max_results=max_results)
+
+    # Merge results
+    all_results = []
+    if platform_results.get("results"):
+        all_results.extend(platform_results["results"])
+    if domain_results.get("results"):
+        all_results.extend(domain_results["results"])
+
+    return {
+        "domain": "stack",
+        "stack": stack,
+        "platform": platform,
+        "query": query,
+        "count": len(all_results[:max_results]),
+        "results": all_results[:max_results]
+    }
+
+
+def persist_blueprint(query, output_dir=None, project_name=None, page=None):
+    """Generate and persist architecture blueprint from search results"""
+    if output_dir is None:
+        output_dir = Path.cwd() / "architecture-blueprint"
+
+    output_dir = Path(output_dir)
+
+    # Run multi-domain search
+    domains_to_search = ["reasoning", "architecture", "snippet", "gradle", "performance", "security", "antipattern"]
+    all_results = {}
+
+    for domain in domains_to_search:
+        result = search(query, domain=domain, max_results=5)
+        if result.get("results"):
+            all_results[domain] = result["results"]
+
+    # Detect platform
+    platform = None
+    for kw in ["android", "ios", "flutter", "react-native", "react native"]:
+        if kw in query.lower():
+            platform = kw.replace(" ", "-")
+            break
+    if not platform:
+        platform = "android"
+
+    # Get platform guidelines
+    platform_result = search_platform(query, platform, max_results=5)
+    if platform_result.get("results"):
+        all_results["platform"] = platform_result["results"]
+
+    # Generate blueprint markdown
+    pname = project_name or "MyApp"
+    lines = [
+        f"# Architecture Blueprint - {pname}",
+        f"",
+        f"**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M')}",
+        f"**Query:** {query}",
+        f"**Platform:** {platform}",
+        f"",
+    ]
+
+    if "reasoning" in all_results:
+        lines.append("## Product Recommendation")
+        for r in all_results["reasoning"][:1]:
+            for k, v in r.items():
+                lines.append(f"- **{k}:** {v}")
+        lines.append("")
+
+    if "architecture" in all_results:
+        lines.append("## Architecture")
+        for r in all_results["architecture"][:2]:
+            for k, v in r.items():
+                lines.append(f"- **{k}:** {v}")
+            lines.append("")
+
+    if "gradle" in all_results:
+        lines.append("## Dependencies")
+        for r in all_results["gradle"]:
+            name = r.get("Name", "")
+            impl = r.get("Implementation", "")
+            lines.append(f"- **{name}:** `{impl}`")
+        lines.append("")
+
+    if "performance" in all_results:
+        lines.append("## Performance Rules")
+        for r in all_results["performance"][:3]:
+            issue = r.get("Issue", "")
+            do = r.get("Do", "")
+            lines.append(f"- **{issue}:** {do}")
+        lines.append("")
+
+    if "security" in all_results:
+        lines.append("## Security Checklist")
+        for r in all_results["security"][:3]:
+            threat = r.get("Threat", "")
+            mitigation = r.get("Mitigation", "")
+            lines.append(f"- **{threat}:** {mitigation}")
+        lines.append("")
+
+    if "antipattern" in all_results:
+        lines.append("## Anti-Patterns to Avoid")
+        for r in all_results["antipattern"][:3]:
+            name = r.get("Name", "")
+            fix = r.get("Fix", "")
+            lines.append(f"- **{name}:** {fix}")
+        lines.append("")
+
+    if "platform" in all_results:
+        lines.append(f"## {platform.title()} Best Practices")
+        for r in all_results["platform"][:5]:
+            guideline = r.get("Guideline", "")
+            desc = r.get("Do", "")
+            lines.append(f"- **{guideline}:** {desc}")
+        lines.append("")
+
+    content = "\n".join(lines)
+
+    # Write files
+    if page:
+        pages_dir = output_dir / "pages"
+        pages_dir.mkdir(parents=True, exist_ok=True)
+        filepath = pages_dir / f"{page}.md"
+    else:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        filepath = output_dir / "MASTER.md"
+
+    filepath.write_text(content, encoding="utf-8")
+
+    return {
+        "file": str(filepath),
+        "sections": list(all_results.keys()),
+        "total_entries": sum(len(v) for v in all_results.values()),
+    }

package/assets/scripts/search.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Mobile Best Practices Search - BM25 search engine for mobile development
+Usage: python search.py "<query>" [--domain <domain>] [--platform <platform>] [--stack <stack>] [--persist] [--max-results 3]
+
+Domains: architecture, ui, template, antipattern, reasoning, library, performance, testing, security, snippet, gradle
+Platforms: android, ios, flutter, react-native
+Stacks: compose, jetpack-compose, material3, hilt, room, kotlin, swiftui, combine, uikit, swift, flutter, dart, bloc, riverpod, react-native, rn, hooks, typescript, redux
+"""
+
+import argparse
+from core import (
+    CSV_CONFIG, AVAILABLE_PLATFORMS, AVAILABLE_STACKS, MAX_RESULTS,
+    search, search_platform, search_stack, persist_blueprint
+)
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("domain") == "platform":
+        output.append(f"## Mobile Best Practices - Platform Guidelines")
+        output.append(f"**Platform:** {result['platform']} | **Query:** {result['query']}")
+    elif result.get("domain") == "stack":
+        output.append(f"## Mobile Best Practices - Stack Search")
+        output.append(f"**Stack:** {result['stack']} ({result.get('platform', '')}) | **Query:** {result['query']}")
+    else:
+        output.append(f"## Mobile Best Practices - Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+
+    file_info = result.get('file', '')
+    if file_info:
+        output.append(f"**Source:** {file_info} | **Found:** {result['count']} results\n")
+    else:
+        output.append(f"**Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Mobile Best Practices Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--platform", "-p", choices=AVAILABLE_PLATFORMS, help="Platform-specific search (android, ios, flutter, react-native)")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (compose, swiftui, flutter, react-native, etc.)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--filter-platform", "-fp", choices=AVAILABLE_PLATFORMS, help="Filter any domain results by platform")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    parser.add_argument("--persist", action="store_true", help="Save results to architecture blueprint file")
+    parser.add_argument("--project-name", "-pn", help="Project name for blueprint (default: MyApp)")
+    parser.add_argument("--page", help="Generate page-specific blueprint override")
+
+    args = parser.parse_args()
+
+    # Persist mode
+    if args.persist:
+        result = persist_blueprint(
+            args.query,
+            project_name=args.project_name,
+            page=args.page
+        )
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(f"Blueprint saved to: {result['file']}")
+            print(f"Sections: {', '.join(result['sections'])}")
+            print(f"Total entries: {result['total_entries']}")
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Platform search takes priority
+    elif args.platform:
+        result = search_platform(args.query, args.platform, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    else:
+        result = search(args.query, args.domain, args.max_results, filter_platform=args.filter_platform)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))