Atlassian Templates

#!/usr/bin/env python3
"""Template Scaffolder - Generate Confluence/Jira template scaffolds from specs.

Reads a template specification and generates ready-to-deploy Confluence
storage format or Jira description markup.

Usage:
    python template_scaffolder.py --spec spec.json --format confluence
    python template_scaffolder.py --spec spec.json --format jira --json
    python template_scaffolder.py --example
"""

import argparse
import json
import sys


CONFLUENCE_SECTION_TEMPLATES = {
    "header_panel": '{panel:title=__TITLE__|borderColor=#0052cc}\n__CONTENT__\n{panel}\n',
    "info_block": '{info}\n__CONTENT__\n{info}\n',
    "warning_block": '{warning}\n__CONTENT__\n{warning}\n',
    "table": '| __HEADERS__ |\n| __SEPARATOR__ |\n| __ROWS__ |\n',
    "task_list": '{tasks}\n__ITEMS__\n{tasks}\n',
    "expand": '{expand:title=__TITLE__}\n__CONTENT__\n{expand}\n',
    "heading": 'h__LEVEL__. __TITLE__\n',
    "toc": '{toc:maxLevel=3}\n',
}


def load_data(path: str) -> dict:
    with open(path, "r") as f:
        return json.load(f)


def generate_confluence(spec: dict) -> str:
    """Generate Confluence storage format template."""
    name = spec.get("name", "Untitled Template")
    sections = spec.get("sections", [])
    metadata = spec.get("metadata", {})

    output = []

    # Header panel
    meta_lines = []
    for key, value in metadata.items():
        meta_lines.append(f"**{key}**: {value}")
    if meta_lines:
        panel = CONFLUENCE_SECTION_TEMPLATES["header_panel"]
        panel = panel.replace("__TITLE__", name)
        panel = panel.replace("__CONTENT__", "\n".join(meta_lines))
        output.append(panel)

    # TOC
    if spec.get("include_toc", True):
        output.append(CONFLUENCE_SECTION_TEMPLATES["toc"])

    # Sections
    for section in sections:
        sec_type = section.get("type", "heading")
        title = section.get("title", "Section")
        content = section.get("content", "[Add content here]")
        level = section.get("level", 2)

        if sec_type == "heading":
            heading = CONFLUENCE_SECTION_TEMPLATES["heading"]
            heading = heading.replace("__LEVEL__", str(level))
            heading = heading.replace("__TITLE__", title)
            output.append(heading)
            output.append(content + "\n")

        elif sec_type == "table":
            headers = section.get("headers", ["Column 1", "Column 2"])
            rows = section.get("rows", 3)
            heading = CONFLUENCE_SECTION_TEMPLATES["heading"].replace("__LEVEL__", str(level)).replace("__TITLE__", title)
            output.append(heading)
            header_row = " | ".join(headers)
            separator = " | ".join(["---"] * len(headers))
            row_template = " | ".join(["[Enter value]"] * len(headers))
            row_lines = "\n".join([f"| {row_template} |"] * rows)
            output.append(f"| {header_row} |\n| {separator} |\n{row_lines}\n")

        elif sec_type == "task_list":
            heading = CONFLUENCE_SECTION_TEMPLATES["heading"].replace("__LEVEL__", str(level)).replace("__TITLE__", title)
            output.append(heading)
            items = section.get("items", ["Task 1", "Task 2", "Task 3"])
            item_lines = "\n".join([f"- [ ] {item}" for item in items])
            tasks = CONFLUENCE_SECTION_TEMPLATES["task_list"].replace("__ITEMS__", item_lines)
            output.append(tasks)

        elif sec_type == "expand":
            expand = CONFLUENCE_SECTION_TEMPLATES["expand"]
            expand = expand.replace("__TITLE__", title)
            expand = expand.replace("__CONTENT__", content)
            output.append(expand)

        elif sec_type == "info":
            heading = CONFLUENCE_SECTION_TEMPLATES["heading"].replace("__LEVEL__", str(level)).replace("__TITLE__", title)
            output.append(heading)
            info = CONFLUENCE_SECTION_TEMPLATES["info_block"].replace("__CONTENT__", content)
            output.append(info)

    return "\n".join(output)


def generate_jira(spec: dict) -> str:
    """Generate Jira description template."""
    name = spec.get("name", "Untitled")
    sections = spec.get("sections", [])

    output = []
    for section in sections:
        title = section.get("title", "Section")
        content = section.get("content", "[Add details]")
        sec_type = section.get("type", "heading")

        output.append(f"## {title}")

        if sec_type == "table":
            headers = section.get("headers", ["Column 1", "Column 2"])
            output.append("| " + " | ".join(headers) + " |")
            output.append("| " + " | ".join(["---"] * len(headers)) + " |")
            for _ in range(section.get("rows", 2)):
                output.append("| " + " | ".join([""] * len(headers)) + " |")
        elif sec_type == "task_list":
            items = section.get("items", ["Item 1", "Item 2"])
            for item in items:
                output.append(f"- [ ] {item}")
        else:
            output.append(content)

        output.append("")

    return "\n".join(output)


def scaffold_template(spec: dict, fmt: str) -> dict:
    if fmt == "confluence":
        content = generate_confluence(spec)
    else:
        content = generate_jira(spec)

    return {
        "name": spec.get("name", "Untitled"),
        "format": fmt,
        "section_count": len(spec.get("sections", [])),
        "content": content,
    }


def print_report(result: dict) -> None:
    print(f"\nTemplate Scaffold: {result['name']}")
    print(f"Format: {result['format']}  |  Sections: {result['section_count']}")
    print("=" * 60)
    print(result["content"])


def print_example() -> None:
    example = {
        "name": "Sprint Retrospective",
        "include_toc": True,
        "metadata": {
            "Sprint": "[Sprint Number]",
            "Date": "{date}",
            "Team": "[Team Name]",
            "Facilitator": "@facilitator",
        },
        "sections": [
            {"type": "heading", "title": "Sprint Overview", "level": 2, "content": "**Sprint Goal**: [Goal]\n**Velocity**: [X points]\n**Completed**: [X/Y stories]"},
            {"type": "heading", "title": "What Went Well", "level": 2, "content": "- [Positive item 1]\n- [Positive item 2]"},
            {"type": "heading", "title": "What Needs Improvement", "level": 2, "content": "- [Challenge 1]\n- [Challenge 2]"},
            {"type": "table", "title": "Improvement Ideas", "level": 2, "headers": ["Idea", "Votes", "Owner", "Target Sprint"], "rows": 3},
            {"type": "task_list", "title": "Action Items", "level": 2, "items": ["Action 1 - @owner - Due: [Date]", "Action 2 - @owner - Due: [Date]"]},
        ],
    }
    print(json.dumps(example, indent=2))


def main():
    parser = argparse.ArgumentParser(description="Generate Confluence/Jira template scaffolds.")
    parser.add_argument("--spec", type=str, help="Path to template spec JSON file")
    parser.add_argument("--format", choices=["confluence", "jira"], default="confluence", help="Output format")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--example", action="store_true", help="Print example spec and exit")
    args = parser.parse_args()

    if args.example:
        print_example()
        return
    if not args.spec:
        parser.error("--spec is required")

    spec = load_data(args.spec)
    result = scaffold_template(spec, args.format)
    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print_report(result)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Template Usage Analyzer - Analyze template adoption and effectiveness.

Reads template usage data and produces adoption metrics, quality scores,
and recommendations for template optimization.

Usage:
    python template_usage_analyzer.py --usage usage.json
    python template_usage_analyzer.py --usage usage.json --json
    python template_usage_analyzer.py --example
"""

import argparse
import json
import sys
from datetime import datetime


def load_data(path: str) -> dict:
    with open(path, "r") as f:
        return json.load(f)


def analyze_usage(data: dict) -> dict:
    org = data.get("organization", "Unknown")
    templates = data.get("templates", [])
    total_pages = data.get("total_pages_created", 0)

    results = []
    total_from_template = 0

    for t in templates:
        name = t.get("name", "Unknown")
        uses = t.get("uses_30d", 0)
        total_from_template += uses
        created_date = t.get("created_date", "Unknown")
        last_updated = t.get("last_updated", "Unknown")
        quality_score = 0

        # Quality checks
        has_instructions = t.get("has_instructions", False)
        has_example = t.get("has_example", False)
        has_owner = t.get("has_owner", False)
        section_count = t.get("section_count", 0)
        has_dynamic_content = t.get("has_dynamic_content", False)

        if has_instructions:
            quality_score += 20
        if has_example:
            quality_score += 20
        if has_owner:
            quality_score += 15
        if section_count >= 3:
            quality_score += 15
        elif section_count >= 1:
            quality_score += 10
        if has_dynamic_content:
            quality_score += 15
        # Version freshness
        if last_updated != "Unknown":
            try:
                updated_dt = datetime.strptime(last_updated, "%Y-%m-%d")
                days_since = (datetime.now() - updated_dt).days
                if days_since <= 90:
                    quality_score += 15
                elif days_since <= 180:
                    quality_score += 10
                elif days_since <= 365:
                    quality_score += 5
            except ValueError:
                pass

        if quality_score >= 80:
            quality_rating = "Excellent"
        elif quality_score >= 60:
            quality_rating = "Good"
        elif quality_score >= 40:
            quality_rating = "Fair"
        else:
            quality_rating = "Poor"

        results.append({
            "name": name,
            "uses_30d": uses,
            "created_date": created_date,
            "last_updated": last_updated,
            "quality_score": quality_score,
            "quality_rating": quality_rating,
            "has_instructions": has_instructions,
            "has_example": has_example,
            "has_owner": has_owner,
            "section_count": section_count,
            "has_dynamic_content": has_dynamic_content,
        })

    results.sort(key=lambda x: x["uses_30d"], reverse=True)

    adoption_rate = round(total_from_template / total_pages * 100, 1) if total_pages > 0 else 0
    avg_quality = round(sum(r["quality_score"] for r in results) / len(results), 1) if results else 0

    # Recommendations
    recs = []
    unused = [r for r in results if r["uses_30d"] == 0]
    if unused:
        recs.append(f"{len(unused)} template(s) with zero usage in 30 days. Review for deprecation or promotion.")
    low_quality = [r for r in results if r["quality_rating"] == "Poor"]
    if low_quality:
        names = ", ".join(r["name"] for r in low_quality[:3])
        recs.append(f"Low quality templates: {names}. Add instructions, examples, and assign owners.")
    if adoption_rate < 50:
        recs.append(f"Template adoption is {adoption_rate:.0f}% (target: 70%+). Promote templates in team channels and pin to space sidebars.")
    no_owner = [r for r in results if not r["has_owner"]]
    if no_owner:
        recs.append(f"{len(no_owner)} template(s) without an owner. Assign owners for maintenance accountability.")

    return {
        "organization": org,
        "analysis_date": datetime.now().strftime("%Y-%m-%d"),
        "total_templates": len(results),
        "total_pages_created": total_pages,
        "pages_from_templates": total_from_template,
        "adoption_rate_pct": adoption_rate,
        "avg_quality_score": avg_quality,
        "templates": results,
        "recommendations": recs,
    }


def print_report(result: dict) -> None:
    print(f"\nTemplate Usage Analysis: {result['organization']}")
    print(f"Date: {result['analysis_date']}")
    print("=" * 65)
    print(f"Templates: {result['total_templates']}  |  Adoption: {result['adoption_rate_pct']:.0f}%  |  Avg Quality: {result['avg_quality_score']:.0f}/100")

    print(f"\nTemplate Details:")
    print(f"  {'Template':<30} {'Uses':>6} {'Quality':>8} {'Rating':<12} {'Updated'}")
    print(f"  {'-'*30} {'-'*6} {'-'*8} {'-'*12} {'-'*12}")
    for t in result["templates"]:
        name = t["name"][:28] + ".." if len(t["name"]) > 30 else t["name"]
        print(f"  {name:<30} {t['uses_30d']:>6} {t['quality_score']:>7}% {t['quality_rating']:<12} {t['last_updated']}")

    if result["recommendations"]:
        print(f"\nRecommendations:")
        for i, r in enumerate(result["recommendations"], 1):
            print(f"  {i}. {r}")
    print()


def print_example() -> None:
    example = {
        "organization": "Acme Corp",
        "total_pages_created": 150,
        "templates": [
            {"name": "Meeting Notes", "uses_30d": 45, "created_date": "2025-06-01", "last_updated": "2026-02-15", "has_instructions": True, "has_example": True, "has_owner": True, "section_count": 5, "has_dynamic_content": True},
            {"name": "Sprint Retrospective", "uses_30d": 12, "created_date": "2025-08-01", "last_updated": "2026-01-10", "has_instructions": True, "has_example": False, "has_owner": True, "section_count": 4, "has_dynamic_content": False},
            {"name": "Old Project Template", "uses_30d": 0, "created_date": "2024-03-01", "last_updated": "2024-06-01", "has_instructions": False, "has_example": False, "has_owner": False, "section_count": 2, "has_dynamic_content": False},
        ],
    }
    print(json.dumps(example, indent=2))


def main():
    parser = argparse.ArgumentParser(description="Analyze template adoption and effectiveness.")
    parser.add_argument("--usage", type=str, help="Path to usage data JSON file")
    parser.add_argument("--json", action="store_true", help="Output results as JSON")
    parser.add_argument("--example", action="store_true", help="Print example data and exit")
    args = parser.parse_args()

    if args.example:
        print_example()
        return
    if not args.usage:
        parser.error("--usage is required (use --example to see the expected format)")

    data = load_data(args.usage)
    result = analyze_usage(data)
    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print_report(result)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Template Validator - Validate templates against quality standards.

Reads a template and checks it against quality criteria including
structure, instructions, completeness, and maintainability.

Usage:
    python template_validator.py --template template.json
    python template_validator.py --template template.json --json
    python template_validator.py --example
"""

import argparse
import json
import sys
from datetime import datetime


QUALITY_CHECKS = [
    {"id": "name", "weight": 10, "description": "Template has a descriptive name (>5 chars)"},
    {"id": "owner", "weight": 10, "description": "Template has a designated owner"},
    {"id": "description", "weight": 10, "description": "Template has a usage description"},
    {"id": "sections", "weight": 15, "description": "Template has 3+ structured sections"},
    {"id": "instructions", "weight": 15, "description": "Sections include inline instructions or placeholders"},
    {"id": "example", "weight": 10, "description": "A completed example is available"},
    {"id": "dynamic", "weight": 10, "description": "Uses dynamic content (macros, dates, Jira queries)"},
    {"id": "version", "weight": 5, "description": "Version number is tracked"},
    {"id": "freshness", "weight": 10, "description": "Updated within the last 12 months"},
    {"id": "labels", "weight": 5, "description": "Template has categorization labels"},
]


def load_data(path: str) -> dict:
    with open(path, "r") as f:
        return json.load(f)


def validate_template(data: dict) -> dict:
    name = data.get("name", "")
    results = []
    total_weight = 0
    earned_weight = 0

    # Name check
    check = {"id": "name", "weight": 10}
    passed = len(name.strip()) > 5
    results.append({"check": "name", "passed": passed, "weight": 10, "detail": f"Name: '{name}'"})
    total_weight += 10
    if passed:
        earned_weight += 10

    # Owner
    passed = bool(data.get("owner", "").strip())
    results.append({"check": "owner", "passed": passed, "weight": 10, "detail": f"Owner: {data.get('owner', 'Not set')}"})
    total_weight += 10
    if passed:
        earned_weight += 10

    # Description
    desc = data.get("description", "")
    passed = len(desc.strip()) > 20
    results.append({"check": "description", "passed": passed, "weight": 10, "detail": f"Description length: {len(desc)} chars"})
    total_weight += 10
    if passed:
        earned_weight += 10

    # Sections
    sections = data.get("sections", [])
    passed = len(sections) >= 3
    results.append({"check": "sections", "passed": passed, "weight": 15, "detail": f"Sections: {len(sections)}"})
    total_weight += 15
    if passed:
        earned_weight += 15

    # Instructions
    has_instructions = sum(1 for s in sections if s.get("has_instructions", False) or "[" in s.get("content", ""))
    passed = has_instructions >= len(sections) * 0.5 if sections else False
    results.append({"check": "instructions", "passed": passed, "weight": 15, "detail": f"Sections with instructions: {has_instructions}/{len(sections)}"})
    total_weight += 15
    if passed:
        earned_weight += 15

    # Example
    passed = data.get("has_example", False)
    results.append({"check": "example", "passed": passed, "weight": 10})
    total_weight += 10
    if passed:
        earned_weight += 10

    # Dynamic content
    passed = data.get("has_dynamic_content", False)
    results.append({"check": "dynamic", "passed": passed, "weight": 10})
    total_weight += 10
    if passed:
        earned_weight += 10

    # Version
    passed = bool(data.get("version", ""))
    results.append({"check": "version", "passed": passed, "weight": 5, "detail": f"Version: {data.get('version', 'Not set')}"})
    total_weight += 5
    if passed:
        earned_weight += 5

    # Freshness
    last_updated = data.get("last_updated", "")
    freshness_passed = False
    if last_updated:
        try:
            updated_dt = datetime.strptime(last_updated, "%Y-%m-%d")
            days = (datetime.now() - updated_dt).days
            freshness_passed = days <= 365
        except ValueError:
            pass
    results.append({"check": "freshness", "passed": freshness_passed, "weight": 10, "detail": f"Last updated: {last_updated or 'Unknown'}"})
    total_weight += 10
    if freshness_passed:
        earned_weight += 10

    # Labels
    labels = data.get("labels", [])
    passed = len(labels) >= 1
    results.append({"check": "labels", "passed": passed, "weight": 5, "detail": f"Labels: {', '.join(labels) if labels else 'None'}"})
    total_weight += 5
    if passed:
        earned_weight += 5

    score = round(earned_weight / total_weight * 100, 1) if total_weight > 0 else 0
    if score >= 85:
        rating = "Production Ready"
    elif score >= 65:
        rating = "Needs Minor Fixes"
    elif score >= 40:
        rating = "Needs Improvement"
    else:
        rating = "Not Ready"

    failures = [r for r in results if not r["passed"]]
    recs = []
    for f in failures:
        check_def = next((c for c in QUALITY_CHECKS if c["id"] == f["check"]), None)
        if check_def:
            recs.append(f"Fix: {check_def['description']}")

    return {
        "template_name": name,
        "score": score,
        "rating": rating,
        "checks_passed": sum(1 for r in results if r["passed"]),
        "checks_total": len(results),
        "results": results,
        "recommendations": recs,
    }


def print_report(result: dict) -> None:
    print(f"\nTemplate Validation: {result['template_name']}")
    print("=" * 55)
    print(f"Score: {result['score']:.0f}/100 ({result['rating']})")
    print(f"Checks: {result['checks_passed']}/{result['checks_total']} passed")

    print(f"\nChecks:")
    for r in result["results"]:
        status = "PASS" if r["passed"] else "FAIL"
        detail = f"  ({r.get('detail', '')})" if r.get("detail") else ""
        check_def = next((c for c in QUALITY_CHECKS if c["id"] == r["check"]), {})
        print(f"  [{status}] {check_def.get('description', r['check'])}{detail}")

    if result["recommendations"]:
        print(f"\nActions Needed:")
        for i, r in enumerate(result["recommendations"], 1):
            print(f"  {i}. {r}")
    print()


def print_example() -> None:
    example = {
        "name": "Sprint Retrospective Template",
        "owner": "Jane Smith",
        "description": "Standard template for sprint retrospective meetings. Covers what went well, challenges, and action items.",
        "version": "2.1",
        "last_updated": "2026-02-15",
        "labels": ["sprint", "retro", "agile"],
        "has_example": True,
        "has_dynamic_content": True,
        "sections": [
            {"title": "Sprint Overview", "content": "**Sprint**: [Number]\n**Velocity**: [X points]", "has_instructions": True},
            {"title": "What Went Well", "content": "- [Positive item]", "has_instructions": True},
            {"title": "Challenges", "content": "- [Challenge]", "has_instructions": True},
            {"title": "Action Items", "content": "- [ ] [Action] - @owner - [Date]", "has_instructions": True},
        ],
    }
    print(json.dumps(example, indent=2))


def main():
    parser = argparse.ArgumentParser(description="Validate templates against quality standards.")
    parser.add_argument("--template", type=str, help="Path to template JSON file")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--example", action="store_true", help="Print example and exit")
    args = parser.parse_args()

    if args.example:
        print_example()
        return
    if not args.template:
        parser.error("--template is required")

    data = load_data(args.template)
    result = validate_template(data)
    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print_report(result)


if __name__ == "__main__":
    main()