msra-codegen 0.1.0__py3-none-any.whl

msra_codegen/funcresult.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .python_render import render_expr
+
+FUNCRESULT_RESULT_TYPES = {"JSON", "TEXT", "IMAGE"}
+
+
+def parse_funcresult_reference(expr: dict[str, Any]) -> tuple[str, str, str, list[dict[str, Any]]]:
+    parts = expr.get("parts", [])
+    if len(parts) < 4 or parts[0].get("kind") != "name" or str(parts[0].get("value")) != "FUNCRESULT":
+        raise ValueError("FUNCRESULT references must use the form <FUNCRESULT.<function>.<example>.<kind>>.")
+
+    function_part = parts[1]
+    example_part = parts[2]
+    result_part = parts[3]
+    if function_part.get("kind") != "name":
+        raise ValueError("FUNCRESULT references must name the source function immediately after FUNCRESULT.")
+    if example_part.get("kind") != "name":
+        raise ValueError(
+            "FUNCRESULT references must name the source example before the result kind, for example "
+            "<FUNCRESULT.<function>.<example>.<kind>>."
+        )
+    if result_part.get("kind") != "name":
+        raise ValueError("FUNCRESULT references must include a result kind after the source example: JSON, TEXT, or IMAGE.")
+
+    result_kind = str(result_part.get("value"))
+    if result_kind not in FUNCRESULT_RESULT_TYPES:
+        raise ValueError("FUNCRESULT references must use the result kind JSON, TEXT, or IMAGE.")
+
+    function_id = str(function_part.get("value"))
+    example_name = str(example_part.get("value"))
+    tail_parts = list(parts[4:])
+    if result_kind != "JSON" and tail_parts:
+        raise ValueError(
+            f"FUNCRESULT.{function_id}.{example_name}.{result_kind} does not allow further path access. "
+            "Use JSON if you need to address nested elements."
+        )
+    for tail_part in tail_parts:
+        if tail_part.get("kind") == "key":
+            validate_funcresult_key_selector(tail_part.get("value"), function_id, example_name)
+
+    return function_id, example_name, result_kind, tail_parts
+
+
+def collect_funcresult_dependencies(expr: Any) -> set[str]:
+    dependencies: set[str] = set()
+
+    def walk(node: Any) -> None:
+        if isinstance(node, list):
+            for item in node:
+                walk(item)
+            return
+        if not isinstance(node, dict):
+            return
+        kind = node.get("kind")
+        if kind == "ref":
+            parts = node.get("parts", [])
+            if parts and parts[0].get("kind") == "name" and str(parts[0].get("value")) == "FUNCRESULT":
+                function_id, example_name, _result_kind, _tail_parts = parse_funcresult_reference(node)
+                dependencies.add(readme_example_key(function_id, example_name))
+            for part in parts:
+                walk(part.get("value"))
+            return
+        if kind == "inline_table":
+            for item in node.get("items", []):
+                walk(item.get("value"))
+            return
+        if kind == "array":
+            for item in node.get("items", []):
+                walk(item)
+            return
+        if kind == "sequence":
+            for item in node.get("items", []):
+                walk(item)
+            return
+        if kind == "merge":
+            for part in node.get("parts", []):
+                walk(part)
+            return
+        if kind == "call":
+            walk(node.get("callee"))
+            for arg in node.get("args", []):
+                walk(arg.get("value"))
+            return
+        if kind == "index":
+            walk(node.get("value"))
+            walk(node.get("index"))
+            return
+
+    walk(expr)
+    return dependencies
+
+
+def render_funcresult_reference(
+    expr: dict[str, Any],
+    base_expr: str,
+    *,
+    index_self_ref: str = "api",
+) -> str:
+    function_id, example_name, _result_kind, tail_parts = parse_funcresult_reference(expr)
+    rendered = base_expr
+    for tail_part in tail_parts:
+        tail_kind = tail_part.get("kind")
+        if tail_kind == "index":
+            rendered += f"[{render_expr(tail_part.get('value'), self_ref=index_self_ref)}]"
+        elif tail_kind == "key":
+            rendered += f"[{render_funcresult_key_selector(tail_part.get('value'), rendered)}]"
+        elif tail_kind == "name":
+            rendered += f".{tail_part.get('value')}"
+        else:
+            raise ValueError(
+                f"Unsupported FUNCRESULT tail part kind {tail_kind!r} for source example "
+                f"[app.func.{function_id}.examples.{example_name}]."
+            )
+    return rendered
+
+
+def render_funcresult_key_selector(index_expr: Any, data_expr: str) -> str:
+    index_value = readme_key_selector_number(index_expr)
+    if index_value is None:
+        raise ValueError("FUNCRESULT @Key selector requires an integer id greater than or equal to -1.")
+    if index_value == 0:
+        return f"next(iter({data_expr}))"
+    if index_value == -1:
+        return f"next(reversed({data_expr}))"
+    if index_value < -1:
+        raise ValueError("FUNCRESULT @Key selector requires an integer id greater than or equal to -1.")
+    return f"list({data_expr})[{index_value}]"
+
+
+def validate_funcresult_key_selector(index_expr: Any, function_id: str, example_name: str) -> None:
+    index_value = readme_key_selector_number(index_expr)
+    if index_value is None or index_value < -1:
+        raise ValueError(
+            f"FUNCRESULT.{function_id}.{example_name}.JSON uses @Key with an invalid id. "
+            f"Expected an integer greater than or equal to -1."
+        )
+
+
+def readme_key_selector_number(index_expr: Any) -> int | None:
+    if not isinstance(index_expr, dict) or index_expr.get("kind") != "number":
+        return None
+    value = index_expr.get("value")
+    if isinstance(value, bool):
+        return None
+    if not isinstance(value, (int, float)):
+        return None
+    if not float(value).is_integer():
+        return None
+    return int(value)
+
+
+def readme_example_key(function_id: str, example_name: str) -> str:
+    return f"{function_id}::{example_name}"

msra_codegen/generator.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .package_writer import generate_project
+from .project_model import build_project
+
+__all__ = ["build_project", "generate_project"]

msra_codegen/generator_config.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import tomllib
+
+
+CONFIG_PATH = Path(__file__).with_name("config.toml")
+
+
+@lru_cache(maxsize=1)
+def load_generator_config() -> dict[str, Any]:
+    with CONFIG_PATH.open("rb") as handle:
+        data = tomllib.load(handle)
+    return data if isinstance(data, dict) else {}
+
+
+def config_section(*path: str) -> dict[str, Any]:
+    current: Any = load_generator_config()
+    for key in path:
+        if not isinstance(current, dict):
+            return {}
+        current = current.get(key, {})
+    return current if isinstance(current, dict) else {}
+
+
+def config_value(*path: str, default: Any = None) -> Any:
+    current: Any = load_generator_config()
+    for key in path:
+        if not isinstance(current, dict) or key not in current:
+            return default
+        current = current[key]
+    return current

msra_codegen/github_workflows.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .file_utils import write_text
+from .generator_config import config_section
+from .template_engine import render_template
+
+
+def build_github_workflows_context(project: dict[str, Any], package_name: str) -> dict[str, Any]:
+    app = project.get("app", {})
+    github_config = config_section("github", "workflows")
+    tests_config = github_config["tests"]
+    publish_config = github_config["publish"]
+    source_sync_config = github_config["source_sync"]
+    app_sync_config = project.get("app", {}).get("sync", {})
+    package_name_slug = package_name.replace("_", "-")
+    source_msra_path = str(Path(project["source_path"]).name)
+
+    tests_python_version = str(tests_config["python_version"])
+    publish_python_version = str(publish_config["python_version"])
+    source_sync_python_version = str(source_sync_config["python_version"])
+    tests_run_command_shell = str(tests_config["run_command_shell"])
+    tests_headed_run_command_shell = str(tests_config["headed_run_command_shell"])
+    preserved_target_paths = app_sync_config.get("preserved_target_paths", [])
+    if not isinstance(preserved_target_paths, list):
+        raise RuntimeError("app.sync.preserved_target_paths must be a list.")
+    ignored_generated_patterns = app_sync_config.get("ignored_generated_patterns", [])
+    if not isinstance(ignored_generated_patterns, list):
+        raise RuntimeError("app.sync.ignored_generated_patterns must be a list.")
+
+    return {
+        "package_name": package_name,
+        "package_name_slug": package_name_slug,
+        "tests": {
+            "name": str(tests_config["name"]),
+            "schedule_cron": str(tests_config["schedule_cron"]),
+            "runner": list(tests_config["runner"]),
+            "python_version": tests_python_version,
+            "python_version_expr": "${{ inputs.python-version || '" + tests_python_version + "' }}",
+            "checkout_action": str(tests_config["checkout_action"]),
+            "setup_python_action": str(tests_config["setup_python_action"]),
+            "install_commands": list(tests_config["install_commands"]),
+            "run_commands": list(tests_config["run_commands"]),
+            "run_command_shell": tests_run_command_shell,
+            "headed_run_command_shell": tests_headed_run_command_shell,
+            "requires_xvfb": bool(app["disallow_headless"]),
+            "report_playwright_failure_action": str(tests_config["report_playwright_failure_action"]),
+            "report_schema_action": str(tests_config["report_schema_action"]),
+            "github_token_expr": "${{ secrets." + str(tests_config["github_token_secret"]) + " }}",
+            "concurrency_group": str(tests_config["name"]) + "-${{ github.ref }}",
+            "log_path": str(tests_config["log_path"]),
+            "screenshot_path": str(tests_config["screenshot_path"]),
+        },
+        "publish": {
+            "name": str(publish_config["name"]),
+            "python_version": publish_python_version,
+            "branch": str(publish_config["branch"]),
+            "checkout_action": str(publish_config["checkout_action"]),
+            "setup_python_action": str(publish_config["setup_python_action"]),
+            "setup_python_cache": str(publish_config["setup_python_cache"]),
+            "workflow_tests_path": "./.github/workflows/tests.yml",
+            "concurrency_group": str(publish_config["name"]) + "-${{ github.ref }}",
+            "docs_condition_expr": (
+                "${{ github.event_name == 'push' || github.event.inputs.target == 'docs' || github.event.inputs.target == 'all' }}"
+            ),
+            "package_condition_expr": (
+                "${{ github.event_name == 'push' || github.event.inputs.target == 'package' || github.event.inputs.target == 'all' }}"
+            ),
+            "upload_pages_action": str(publish_config["upload_pages_action"]),
+            "deploy_pages_action": str(publish_config["deploy_pages_action"]),
+            "pypi_action": str(publish_config["pypi_action"]),
+            "target_options": list(publish_config["target_options"]),
+            "pages_environment_name": str(publish_config["pages_environment_name"]),
+            "pypi_environment_name": str(publish_config["pypi_environment_name"]),
+            "github_token_expr": "${{ secrets." + str(publish_config["github_token_secret"]) + " }}",
+            "page_url_expr": "${{ steps.deployment.outputs.page_url }}",
+            "pypi_url": f"https://pypi.org/project/{package_name_slug}/",
+        },
+        "source_sync": {
+            "name": str(source_sync_config["name"]),
+            "source_branch": str(source_sync_config["source_branch"]),
+            "target_branch": str(source_sync_config["target_branch"]),
+            "logic_repository": str(source_sync_config["logic_repository"]),
+            "logic_ref": str(source_sync_config["logic_ref"]),
+            "checkout_action": str(source_sync_config["checkout_action"]),
+            "setup_python_action": str(source_sync_config["setup_python_action"]),
+            "python_version": source_sync_python_version,
+            "generator_requirements_path": str(source_sync_config["generator_requirements_path"]),
+            "repo_token_secret": str(source_sync_config["repo_token_secret"]),
+            "repo_token_expr": "${{ secrets." + str(source_sync_config["repo_token_secret"]) + " }}",
+            "repository_expr": "${{ github.repository }}",
+            "commit_user_name": str(source_sync_config["commit_user_name"]),
+            "commit_user_email": str(source_sync_config["commit_user_email"]),
+            "source_msra_path": source_msra_path,
+            "preserved_target_paths": [str(item) for item in preserved_target_paths],
+            "ignored_generated_patterns": [str(item) for item in ignored_generated_patterns],
+        },
+        "makefile": {
+            "package_name": package_name,
+        },
+    }
+
+
+def generate_github_workflows_project(project: dict[str, Any], output_dir: Path, package_name: str) -> None:
+    context = build_github_workflows_context(project, package_name)
+    workflows_root = output_dir / ".github" / "workflows"
+    if workflows_root.exists():
+        shutil.rmtree(workflows_root)
+    workflows_root.mkdir(parents=True, exist_ok=True)
+
+    write_text(
+        output_dir / "Makefile",
+        render_template("Makefile.tpl", context["makefile"]),
+    )
+    write_text(
+        workflows_root / "tests.yml",
+        render_template("github/workflows/tests.yml.tpl", context),
+    )
+    write_text(
+        workflows_root / "source-sync.yml",
+        render_template("github/workflows/source-sync.yml.tpl", context),
+    )
+    write_text(
+        workflows_root / "publish.yml",
+        render_template("github/workflows/publish.yml.tpl", context),
+    )

msra_codegen/gitignore.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .file_utils import write_text
+from .generator_config import config_section
+from .template_engine import render_template
+
+
+def build_gitignore_context() -> dict[str, Any]:
+    gitignore_config = config_section("gitignore")
+    patterns = gitignore_config.get("patterns")
+    if not isinstance(patterns, list) or not patterns:
+        raise RuntimeError("gitignore.patterns must be a non-empty list.")
+
+    normalized_patterns: list[str] = []
+    for index, pattern in enumerate(patterns):
+        if not isinstance(pattern, str):
+            raise TypeError(f"gitignore.patterns[{index}] must be a string.")
+        normalized_patterns.append(pattern.rstrip())
+
+    return {"patterns": normalized_patterns}
+
+
+def generate_gitignore_project(output_dir: Path) -> None:
+    context = build_gitignore_context()
+    write_text(
+        output_dir / ".gitignore",
+        render_template("gitignore.tpl", context),
+    )

msra_codegen/issue_templates.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .file_utils import write_text
+from .template_engine import render_template
+
+
+def build_github_issue_templates_context(project: dict[str, Any]) -> dict[str, Any] | None:
+    app = project.get("app", {})
+    issue_templates = app.get("issue_templates")
+    if issue_templates is None:
+        return None
+    if not isinstance(issue_templates, dict):
+        raise RuntimeError("app.issue_templates must be a table.")
+
+    assignee = str(issue_templates.get("assignee", "")).strip()
+    if not assignee:
+        raise RuntimeError("app.issue_templates.assignee must be a non-empty string.")
+
+    contact_links = build_issue_template_contact_links(app)
+
+    return {
+        "assignee": assignee,
+        "contact_links": contact_links,
+        "yaml_value": lambda value: json.dumps(value, ensure_ascii=False),
+    }
+
+
+def build_issue_template_contact_links(app: dict[str, Any]) -> list[dict[str, str]]:
+    package_owner = str(app.get("package_owner", "")).strip()
+    package_name = str(app.get("package_name", "")).strip()
+    if not package_owner or not package_name:
+        raise RuntimeError("app.package_owner and app.package_name are required to generate issue templates.")
+
+    contact_links: list[dict[str, str]] = [
+        {
+            "name": "📖  Read the docs",
+            "url": f"https://{package_owner.lower()}.github.io/{package_name}/quick_start.html",
+            "about": "Start here for “how-to” questions.",
+        }
+    ]
+
+    social = app.get("social")
+    if social is None:
+        return contact_links
+    if not isinstance(social, dict):
+        raise RuntimeError("app.social must be a table when issue templates are enabled.")
+
+    discord_url = str(social.get("discord", "")).strip()
+    if discord_url:
+        contact_links.append(
+            {
+                "name": "💬  Discord server (Discussions)",
+                "url": discord_url,
+                "about": "General Q&A and community support.",
+            }
+        )
+
+    telegram_url = str(social.get("telegram", "")).strip()
+    if telegram_url:
+        contact_links.append(
+            {
+                "name": "💬  Telegram channel (Discussions)",
+                "url": telegram_url,
+                "about": "General Q&A and community support.",
+            }
+        )
+
+    return contact_links
+
+
+def generate_github_issue_templates_project(project: dict[str, Any], output_dir: Path) -> None:
+    issue_templates_root = output_dir / ".github" / "ISSUE_TEMPLATE"
+    context = build_github_issue_templates_context(project)
+    if issue_templates_root.exists():
+        shutil.rmtree(issue_templates_root)
+    if context is None:
+        return
+
+    issue_templates_root.mkdir(parents=True, exist_ok=True)
+    write_text(
+        issue_templates_root / "config.yml",
+        render_template("github/issue_templates/config.yml.tpl", context),
+    )
+    write_text(
+        issue_templates_root / "bug_report.yml",
+        render_template("github/issue_templates/bug_report.yml.tpl", context),
+    )
+    write_text(
+        issue_templates_root / "documentation_issue.yml",
+        render_template("github/issue_templates/documentation_issue.yml.tpl", context),
+    )
+    write_text(
+        issue_templates_root / "feature_request.yml",
+        render_template("github/issue_templates/feature_request.yml.tpl", context),
+    )

msra_codegen/logo_assets.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from PIL import Image, ImageOps, UnidentifiedImageError
+
+
+LOGO_LIGHT_NAME = "logo-light.webp"
+LOGO_DARK_NAME = "logo-dark.webp"
+
+
+def build_logo_assets(
+    project: dict[str, Any],
+    source_root: Path,
+    static_root: Path,
+) -> dict[str, str] | None:
+    logo_value = str(project.get("app", {}).get("logo") or "").strip()
+    if not logo_value:
+        return None
+
+    source_path = resolve_logo_source_path(source_root, logo_value)
+    if not source_path.is_file():
+        raise FileNotFoundError(f'app.logo points to a missing file: {source_path}')
+
+    source_image = load_logo_image(source_path)
+    source_polarity = detect_logo_polarity(source_image, source_path)
+    light_image, dark_image = build_logo_variants(source_image, source_polarity)
+
+    light_target = static_root / LOGO_LIGHT_NAME
+    dark_target = static_root / LOGO_DARK_NAME
+    save_logo_variant(light_image, light_target)
+    save_logo_variant(dark_image, dark_target)
+    return {
+        "light_name": LOGO_LIGHT_NAME,
+        "dark_name": LOGO_DARK_NAME,
+    }
+
+
+def resolve_logo_source_path(source_root: Path, logo_value: str) -> Path:
+    candidate = Path(logo_value).expanduser()
+    if candidate.is_absolute():
+        return candidate.resolve()
+    return (source_root / candidate).resolve()
+
+
+def load_logo_image(source_path: Path) -> Image.Image:
+    try:
+        with Image.open(source_path) as image:
+            return image.convert("RGBA")
+    except (OSError, UnidentifiedImageError) as exc:
+        raise ValueError(
+            f'app.logo must point to a raster image Pillow can read: {source_path}'
+        ) from exc
+
+
+def detect_logo_polarity(source_image: Image.Image, source_path: Path) -> str:
+    pixels = source_image.load()
+    width, height = source_image.size
+    visible_pixels = 0
+    visible_red_sum = 0
+    for y in range(height):
+        for x in range(width):
+            red, green, blue, alpha = pixels[x, y]
+            if alpha == 0:
+                continue
+            visible_pixels += 1
+            if red != green or green != blue:
+                raise ValueError(
+                    "app.logo must be a monochrome black-and-white raster image; "
+                    f"colored pixel at ({x}, {y}) is RGBA=({red}, {green}, {blue}, {alpha}): {source_path}"
+                )
+            visible_red_sum += red
+    if visible_pixels == 0:
+        raise ValueError(f"app.logo must contain at least one visible pixel: {source_path}")
+    return "white" if visible_red_sum * 2 >= visible_pixels * 255 else "black"
+
+
+def build_logo_variants(source_image: Image.Image, source_polarity: str) -> tuple[Image.Image, Image.Image]:
+    black_variant = source_image if source_polarity == "black" else invert_logo_image(source_image)
+    white_variant = source_image if source_polarity == "white" else invert_logo_image(source_image)
+    return black_variant, white_variant
+
+
+def invert_logo_image(source_image: Image.Image) -> Image.Image:
+    red, green, blue, alpha = source_image.split()
+    rgb = Image.merge("RGB", (red, green, blue))
+    inverted_rgb = ImageOps.invert(rgb)
+    return Image.merge("RGBA", (*inverted_rgb.split(), alpha))
+
+
+def save_logo_variant(source_image: Image.Image, target_path: Path) -> None:
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        source_image.save(target_path, format="WEBP", lossless=True, method=6, exact=True)
+    except (OSError, ValueError) as exc:
+        raise ValueError(
+            f"app.logo output requires WebP support in Pillow: {target_path}"
+        ) from exc