convert_to_readme.py

#!/usr/bin/env python3
"""Convert AWS SAA-03 Solution.txt to README.md format."""

import re
from pathlib import Path

ROOT = Path(__file__).parent
INPUT_FILE = ROOT / "AWS SAA-03 Solution.txt"
OUTPUT_FILE = ROOT / "README.md"

QUESTION_START = re.compile(r"^(\d+)([\]\.])\s*(.*)$")
SEPARATOR = re.compile(r"^-{10,}\s*$")
ANS_ANSWER = re.compile(r"^ans[-\.]\s*(.*)$", re.IGNORECASE)
ANSWER_LINE = re.compile(r"^Answer:\s*(.*)$", re.IGNORECASE)
OPTION_ANSWER = re.compile(r"^\s*([A-F])\.\s+(.+)$")
OPTION_ANSWER_PAREN = re.compile(r"^Answer:\s*([A-F])\)\s*(.*)$", re.IGNORECASE)
ANSWERS_MULTI = re.compile(r"^Answers:\s*(.*)$", re.IGNORECASE)
QUESTION_PROMPT = re.compile(
    r"^(Which|What|How|A solutions architect|An application|The company|Why)\b",
    re.IGNORECASE,
)


def looks_like_answer_line(line: str, in_question_phase: bool) -> bool:
  """Detect answer lines including plain-text answers without option letters."""
  if is_answer_line(line):
    return True
  if not in_question_phase:
    return False
  stripped = line.strip()
  if not stripped or QUESTION_PROMPT.match(stripped):
    return False
  if stripped.startswith(("-", "*", "•")):
    return False
  if re.match(r"^[A-F]\.\s", stripped):
    return True
  # Plain answer after question block (e.g. " Deploy a Gateway Load Balancer...")
  if line.startswith(" ") or line.startswith("\t"):
    return True
  return False


def is_answer_line(line: str) -> bool:
    stripped = line.strip()
    if not stripped:
        return False
    if ANS_ANSWER.match(stripped):
        return True
    if ANSWER_LINE.match(stripped):
        return True
    if ANSWERS_MULTI.match(stripped):
        return True
    if OPTION_ANSWER_PAREN.match(stripped):
        return True
    if OPTION_ANSWER.match(stripped):
        return True
    return False


def extract_answer(line: str) -> str | None:
    stripped = line.strip()
    m = ANS_ANSWER.match(stripped)
    if m:
        return m.group(1).strip()
    m = ANSWER_LINE.match(stripped)
    if m:
        return m.group(1).strip()
    m = ANSWERS_MULTI.match(stripped)
    if m:
        return m.group(1).strip()
    m = OPTION_ANSWER_PAREN.match(stripped)
    if m:
        letter, rest = m.group(1), m.group(2).strip()
        return f"{letter}) {rest}" if rest else f"{letter})"
    m = OPTION_ANSWER.match(stripped)
    if m:
        return f"{m.group(1)}. {m.group(2).strip()}"
    if looks_like_answer_line(line, in_question_phase=True):
        return stripped
    return None


def parse_questions(text: str) -> list[dict]:
    lines = text.splitlines()
    questions: list[dict] = []
    current: dict | None = None
    body_lines: list[str] = []
    answer_lines: list[str] = []
    explanation_lines: list[str] = []
    phase = "question"  # question | answer | explanation

    def flush():
        nonlocal current, body_lines, answer_lines, explanation_lines, phase
        if current is None:
            return
        question_text = " ".join(l.strip() for l in body_lines if l.strip())
        answer = " ".join(answer_lines).strip()
        explanation = "\n".join(l.rstrip() for l in explanation_lines if l.strip()).strip()
        questions.append(
            {
                "number": int(current["number"]),
                "question": question_text,
                "answer": answer,
                "explanation": explanation,
            }
        )
        current = None
        body_lines = []
        answer_lines = []
        explanation_lines = []
        phase = "question"

    for line in lines:
        if SEPARATOR.match(line.strip()):
            if current and phase in ("answer", "explanation"):
                phase = "explanation"
            continue

        m = QUESTION_START.match(line)
        if m:
            flush()
            current = {"number": m.group(1)}
            first_line = m.group(3).strip()
            if first_line:
                body_lines = [first_line]
            else:
                body_lines = []
            answer_lines = []
            explanation_lines = []
            phase = "question"
            continue

        if current is None:
            continue

        stripped = line.strip()
        if not stripped:
            if phase == "question" and body_lines:
                body_lines.append("")
            elif phase == "explanation":
                explanation_lines.append("")
            continue

        if phase == "question":
            if looks_like_answer_line(line, in_question_phase=True):
                ans = extract_answer(line)
                if ans:
                    answer_lines.append(ans)
                phase = "answer"
            else:
                body_lines.append(stripped)
        elif phase == "answer":
            if is_answer_line(stripped) and not answer_lines:
                ans = extract_answer(stripped)
                if ans:
                    answer_lines.append(ans)
            elif is_answer_line(stripped) and answer_lines:
                ans = extract_answer(stripped)
                if ans:
                    answer_lines.append(ans)
            elif OPTION_ANSWER.match(stripped) and "Choose two" in " ".join(body_lines):
                ans = extract_answer(stripped)
                if ans:
                    answer_lines.append(ans)
            else:
                explanation_lines.append(stripped)
                phase = "explanation"
        else:
            if is_answer_line(stripped) and not answer_lines:
                ans = extract_answer(stripped)
                if ans:
                    answer_lines.append(ans)
                    phase = "answer"
            else:
                explanation_lines.append(stripped)

    flush()
    return questions


def dedupe_questions(questions: list[dict]) -> list[dict]:
    """Keep the richest version when duplicate question numbers exist."""
    by_num: dict[int, dict] = {}
    for q in questions:
        num = q["number"]
        if num not in by_num:
            by_num[num] = q
            continue
        existing = by_num[num]
        existing_score = len(existing["question"]) + len(existing["answer"]) + len(existing["explanation"])
        new_score = len(q["question"]) + len(q["answer"]) + len(q["explanation"])
        if new_score > existing_score:
            by_num[num] = q
    return [by_num[n] for n in sorted(by_num)]


def format_markdown(questions: list[dict]) -> str:
    intro = """# AWS Certified Solutions Architect Associate (SAA-C03) — Exam Questions & Solutions

Comprehensive collection of study materials, practice exam questions, and solved MCQs to help you prepare for the AWS Certified Solutions Architect – Associate (SAA-C03) exam.

Welcome to the AWS SAA-C03 Exam Preparation Repository! This repository is designed to help you prepare for the AWS Certified Solutions Architect - Associate (SAA-C03) exam by providing a comprehensive set of Multiple Choice Questions (MCQs) along with their solutions. Please note that while this resource can be a valuable part of your preparation, it's crucial to cross-check the solutions and not solely rely on them.

## Contents

- **{count}+ MCQs:** This repository includes a diverse set of over {count} multiple-choice questions covering various aspects of the AWS SAA-C03 exam.
- **Detailed Solutions:** Each question is accompanied by a detailed solution, providing explanations and insights to help you understand the concepts thoroughly.

## Important Considerations

- **Stay Updated:** AWS services and features are subject to change. Always cross-check the provided solutions and be aware that AWS might update its services, affecting the correctness of the answers.
- **Use as a Supplement:** This repository should be used as a supplementary resource in conjunction with other study materials. It is not a replacement for hands-on experience and in-depth understanding of AWS services.

## Table of Contents

""".format(count=len(questions))

    toc_lines = []
    for q in questions:
        toc_lines.append(f"- [Question {q['number']}](#question-{q['number']})")
    toc = "\n".join(toc_lines)

    sections = [
        intro,
        toc,
        "\n---\n\n## Questions & Solutions\n",
    ]

    for q in questions:
        block = [f'<a id="question-{q["number"]}"></a>\n\n### Question {q["number"]}\n']
        if q["question"].strip():
            block.append(f"{q['question']}\n")
        else:
            block.append("*Question text not available in source file.*\n")
        if q["answer"]:
            block.append(f"\n**Answer:** {q['answer']}\n")
        if q["explanation"]:
            block.append(f"\n**Explanation:**\n\n{q['explanation']}\n")
        block.append("\n---\n")
        sections.append("".join(block))

    footer = """
## How to Contribute

If you find any errors or have suggestions for improvement, feel free to contribute to this repository. Please use the standard GitHub workflow for making contributions.

## Star the Repository

If you find this repository useful, please consider starring it. Your support helps make this resource more visible to others, aiding them in their exam preparation.

## Disclaimer

While this repository aims to assist you in your exam preparation, it is not a guarantee of success. The best way to prepare is to combine various resources, hands-on experience, and thorough understanding of AWS services.

Good luck with your AWS SAA-C03 exam preparation!
"""
    sections.append(footer)
    return "".join(sections)


def main():
    text = INPUT_FILE.read_text(encoding="utf-8", errors="replace")
    questions = parse_questions(text)
    questions = dedupe_questions(questions)
    markdown = format_markdown(questions)
    OUTPUT_FILE.write_text(markdown, encoding="utf-8")
    print(f"Converted {len(questions)} questions to {OUTPUT_FILE}")
    empty = [q["number"] for q in questions if not q["question"].strip()]
    if empty:
        print(f"Warning: {len(empty)} questions have empty question text: {empty[:10]}...")


if __name__ == "__main__":
    main()