modwire 3.2.0__tar.gz → 4.0.2__tar.gz

modwire-4.0.2/.github/modwire-ecosystem.yml

@@ -0,0 +1,171 @@
+version: 2
+
+packages:
+  core:
+    repository: 9orky/modwire
+    distribution: modwire
+    component: Core
+    role: coordinator
+    lifecycle: active
+    summary: Typed coordination library and ecosystem integration gate.
+    depends_on: [extraction, mermaid, siren]
+  cli:
+    repository: 9orky/modwire-cli
+    distribution: modwire-cli
+    component: CLI
+    role: runtime
+    lifecycle: active
+    summary: Command-line runtime and user-facing workflows.
+    depends_on: [core]
+  extraction:
+    repository: 9orky/modwire-extraction
+    distribution: modwire-extraction
+    component: Extraction
+    role: building_block
+    lifecycle: active
+    summary: Canonical source extraction and normalization.
+  mermaid:
+    repository: 9orky/modwire-mermaid
+    distribution: modwire-mermaid
+    component: Mermaid
+    role: building_block
+    lifecycle: active
+    summary: Typed, deterministic Mermaid source generation.
+  siren:
+    repository: 9orky/modwire-siren
+    distribution: modwire-siren
+    component: Siren
+    role: building_block
+    lifecycle: active
+    summary: Typed Siren hypermedia and OpenAPI integration.
+  mcp:
+    repository: 9orky/modwire-mcp
+    distribution: modwire-mcp
+    component: MCP
+    role: integration
+    lifecycle: incubating
+    summary: MCP surface and future home of scaffolding operations.
+    depends_on: [core]
+
+project:
+  owner: 9orky
+  title: Modwire Ecosystem
+  number: 4
+  visibility: public
+  default_package: core
+  description: Cross-repository roadmap and release coordination for the Modwire ecosystem.
+  governance_url: https://github.com/9orky/modwire/blob/main/docs/governance/github-ecosystem.md
+
+workflows:
+  contract_ref: workflows-v1
+  ci_entrypoint: .github/workflows/ci.yml
+  release_entrypoint: .github/workflows/release.yml
+  verify_reusable: .github/workflows/python-package.yml
+  release_build_reusable: .github/workflows/python-release-build.yml
+  release_assets_reusable: .github/workflows/python-release-assets.yml
+  release_driver: github_release
+  release_event: published
+  release_tag_pattern: ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$
+  artifact_name: python-package-distributions
+  pypi_environment: pypi
+  actions:
+    checkout: actions/checkout@v6
+    setup_python: actions/setup-python@v6
+    upload_artifact: actions/upload-artifact@v7
+    download_artifact: actions/download-artifact@v8
+    publish_pypi: pypa/gh-action-pypi-publish@release/v1
+
+fields:
+  Status:
+    type: single_select
+    options: [Inbox, Ready, In progress, Blocked, Review, Done]
+  Horizon:
+    type: single_select
+    options: [Now, Next, Later]
+  Priority:
+    type: single_select
+    options: [P0, P1, P2, P3]
+  Component:
+    type: single_select
+    source: packages
+  Release train:
+    type: text
+  Target date:
+    type: date
+  Risk:
+    type: single_select
+    options: [Low, Medium, High]
+
+views:
+  - name: Roadmap
+    layout: roadmap
+    group_by: Release train
+    slice_by: Component
+  - name: Now
+    layout: board
+    filter: "Horizon:Now -Status:Done"
+    group_by: Status
+  - name: By package
+    layout: table
+    filter: "-Status:Done"
+    group_by: Repository
+  - name: Blocked
+    layout: table
+    filter: "Status:Blocked"
+    group_by: Component
+  - name: Release readiness
+    layout: table
+    filter: "has:\"Release train\" -Status:Done"
+    group_by: Release train
+  - name: Inbox
+    layout: table
+    filter: "Status:Inbox"
+
+labels:
+  "type:bug":
+    color: "d73a4a"
+    description: Incorrect existing behavior
+  "type:feature":
+    color: "0e8a16"
+    description: New user-facing capability
+  "type:maintenance":
+    color: "c5def5"
+    description: Internal maintenance
+  "type:docs":
+    color: "0075ca"
+    description: Documentation
+  ecosystem:
+    color: "5319e7"
+    description: Cross-package coordination
+  contract:
+    color: "1d76db"
+    description: Public contract or compatibility work
+  breaking:
+    color: "b60205"
+    description: Backward-incompatible change
+  blocked:
+    color: "e99695"
+    description: Blocked by another decision or delivery
+  release-gate:
+    color: "fbca04"
+    description: Must complete before a release
+
+automation:
+  auto_add_filter: "is:open"
+  added_status: Inbox
+  closed_status: Done
+  merged_status: Done
+  archive_filter: "Status:Done updated:<@today-30d"
+
+milestones:
+  scope: repository
+  naming: "<version-or-phase>: <outcome>"
+  close_when_complete: true
+  ecosystem_coordination_field: Release train
+  cross_repository_work: parent_issue_in_modwire_with_sub_issues
+
+cadence:
+  triage: weekly
+  roadmap_review: monthly
+  release_readiness: before_each_package_release
+  project_status_update: monthly

modwire-4.0.2/.github/scripts/reconcile_ecosystem.py

@@ -0,0 +1,405 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from modwire.projects import EcosystemContract, EcosystemDrift, ProjectFieldType
+
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_CONTRACT = ROOT / ".github" / "modwire-ecosystem.yml"
+
+
+def gh(*arguments: str) -> str:
+    result = subprocess.run(
+        ["gh", *arguments],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout
+
+
+def gh_json(*arguments: str) -> Any:
+    return json.loads(gh(*arguments))
+
+
+def load_contract(path: Path) -> EcosystemContract:
+    return EcosystemContract.load_yaml(path)
+
+
+def workflow_drift(contract: EcosystemContract) -> list[str]:
+    errors: list[str] = []
+    workflow_paths = (
+        contract.workflows.ci_entrypoint,
+        contract.workflows.release_entrypoint,
+        contract.workflows.verify_reusable,
+        contract.workflows.release_build_reusable,
+        contract.workflows.release_assets_reusable,
+    )
+    contents: dict[str, str] = {}
+    for relative_path in workflow_paths:
+        path = ROOT / relative_path
+        if not path.is_file():
+            errors.append(f"missing workflow file {relative_path}")
+            continue
+        contents[relative_path] = path.read_text(encoding="utf-8")
+
+    expected_actions = {
+        "actions/checkout": contract.workflows.actions.checkout,
+        "actions/setup-python": contract.workflows.actions.setup_python,
+        "actions/upload-artifact": contract.workflows.actions.upload_artifact,
+        "actions/download-artifact": contract.workflows.actions.download_artifact,
+        "pypa/gh-action-pypi-publish": contract.workflows.actions.publish_pypi,
+    }
+    for path in sorted((ROOT / ".github" / "workflows").glob("*.yml")):
+        text = path.read_text(encoding="utf-8")
+        for action in re.findall(
+            r"(?:actions/(?:checkout|setup-python|upload-artifact|download-artifact)|"
+            r"pypa/gh-action-pypi-publish)@[^\s]+",
+            text,
+        ):
+            name = action.split("@", maxsplit=1)[0]
+            if action != expected_actions[name]:
+                errors.append(f"{path.name}: unmanaged action reference {action}")
+
+    release = contents.get(contract.workflows.release_entrypoint, "")
+    release_build = contents.get(contract.workflows.release_build_reusable, "")
+    verify = contents.get(contract.workflows.verify_reusable, "")
+    required_references = {
+        contract.workflows.release_entrypoint: (
+            contract.workflows.release_build_reusable,
+            contract.workflows.release_assets_reusable,
+            contract.workflows.actions.download_artifact,
+            contract.workflows.actions.publish_pypi,
+        ),
+        contract.workflows.release_build_reusable: (
+            contract.workflows.actions.checkout,
+            contract.workflows.actions.setup_python,
+            contract.workflows.actions.upload_artifact,
+        ),
+        contract.workflows.verify_reusable: (
+            contract.workflows.actions.checkout,
+            contract.workflows.actions.setup_python,
+            contract.workflows.actions.upload_artifact,
+        ),
+        contract.workflows.release_assets_reusable: (
+            contract.workflows.actions.download_artifact,
+        ),
+    }
+    for path, references in required_references.items():
+        text = contents.get(path, "")
+        for reference in references:
+            if reference not in text:
+                errors.append(f"{path}: missing required reference {reference}")
+
+    for forbidden in (
+        "python - <<",
+        "SETUPTOOLS_SCM_PRETEND_VERSION",
+        "softprops/",
+    ):
+        if forbidden in release or forbidden in release_build:
+            errors.append(f"release workflows contain forbidden pattern {forbidden}")
+    if contract.workflows.artifact_name not in release or contract.workflows.artifact_name not in release_build:
+        errors.append("release artifact name differs from the workflow contract")
+    release_assets = contents.get(contract.workflows.release_assets_reusable, "")
+    if (
+        "workflow_call:" not in verify
+        or "workflow_call:" not in release_build
+        or "workflow_call:" not in release_assets
+    ):
+        errors.append("reusable workflows must use workflow_call")
+    if "release:" not in release or "types: [published]" not in release:
+        errors.append("release.yml must be driven by a published GitHub Release")
+    if "skip-existing: true" not in release:
+        errors.append("release.yml must make PyPI publication idempotent")
+    if '--repo "$GITHUB_REPOSITORY"' not in release_assets:
+        errors.append("release assets must target GITHUB_REPOSITORY explicitly")
+    return errors
+
+
+def project_fields(contract: EcosystemContract) -> dict[str, dict[str, Any]]:
+    query = """
+    query($id: ID!) {
+      node(id: $id) {
+        ... on ProjectV2 {
+          fields(first: 100) {
+            nodes {
+              __typename
+              ... on ProjectV2Field { id name dataType }
+              ... on ProjectV2SingleSelectField { id name options { name } }
+            }
+          }
+        }
+      }
+    }
+    """
+    project = gh_json(
+        "project",
+        "view",
+        str(contract.project.number),
+        "--owner",
+        contract.project.owner,
+        "--format",
+        "json",
+    )
+    data = gh_json(
+        "api",
+        "graphql",
+        "-F",
+        f"id={project['id']}",
+        "-f",
+        f"query={query}",
+    )
+    nodes = data["data"]["node"]["fields"]["nodes"]
+    return {node["name"]: node for node in nodes if node.get("name")}
+
+
+def linked_repositories(contract: EcosystemContract) -> set[str]:
+    query = """
+    query($id: ID!) {
+      node(id: $id) {
+        ... on ProjectV2 { repositories(first: 100) { nodes { nameWithOwner } } }
+      }
+    }
+    """
+    project = gh_json(
+        "project",
+        "view",
+        str(contract.project.number),
+        "--owner",
+        contract.project.owner,
+        "--format",
+        "json",
+    )
+    data = gh_json(
+        "api",
+        "graphql",
+        "-F",
+        f"id={project['id']}",
+        "-f",
+        f"query={query}",
+    )
+    nodes = data["data"]["node"]["repositories"]["nodes"]
+    return {node["nameWithOwner"] for node in nodes}
+
+
+def open_work_urls(contract: EcosystemContract) -> set[str]:
+    urls: set[str] = set()
+    for repository in contract.repositories():
+        for kind in ("issue", "pr"):
+            items = gh_json(
+                kind,
+                "list",
+                "--repo",
+                repository,
+                "--state",
+                "open",
+                "--limit",
+                "100",
+                "--json",
+                "url",
+            )
+            urls.update(item["url"] for item in items)
+    return urls
+
+
+def project_item_urls(contract: EcosystemContract) -> set[str]:
+    data = gh_json(
+        "project",
+        "item-list",
+        str(contract.project.number),
+        "--owner",
+        contract.project.owner,
+        "--limit",
+        "1000",
+        "--format",
+        "json",
+    )
+    return {
+        item["content"]["url"]
+        for item in data["items"]
+        if item.get("content", {}).get("url")
+    }
+
+
+def label_drift(contract: EcosystemContract) -> list[str]:
+    errors: list[str] = []
+    for repository in contract.repositories():
+        actual = {
+            label["name"]: label
+            for label in gh_json(
+                "label",
+                "list",
+                "--repo",
+                repository,
+                "--limit",
+                "100",
+                "--json",
+                "name,color,description",
+            )
+        }
+        for name, expected in contract.labels.items():
+            label = actual.get(name)
+            if label is None:
+                errors.append(f"{repository}: missing label {name}")
+                continue
+            if label["color"].lower() != expected.color:
+                errors.append(f"{repository}: label {name} has the wrong color")
+            if label["description"] != expected.description:
+                errors.append(f"{repository}: label {name} has the wrong description")
+    return errors
+
+
+def inspect_live(contract: EcosystemContract) -> EcosystemDrift:
+    errors = workflow_drift(contract)
+    project = gh_json(
+        "project",
+        "view",
+        str(contract.project.number),
+        "--owner",
+        contract.project.owner,
+        "--format",
+        "json",
+    )
+    expected_project = {
+        "title": contract.project.title,
+        "public": contract.project.visibility.value == "public",
+        "shortDescription": contract.project.description,
+        "readme": contract.project_readme(),
+    }
+    for name, expected in expected_project.items():
+        if project[name] != expected:
+            errors.append(f"project {name} differs from the contract")
+
+    expected_repositories = set(contract.repositories())
+    actual_repositories = linked_repositories(contract)
+    for repository in sorted(expected_repositories - actual_repositories):
+        errors.append(f"project is not linked to {repository}")
+    for repository in sorted(actual_repositories - expected_repositories):
+        errors.append(f"project has unmanaged repository {repository}")
+
+    actual_fields = project_fields(contract)
+    for name, expected in contract.fields.items():
+        actual = actual_fields.get(name)
+        if actual is None:
+            errors.append(f"project is missing field {name}")
+            continue
+        if expected.type is ProjectFieldType.SINGLE_SELECT:
+            options = tuple(option["name"] for option in actual.get("options", ()))
+            if options != contract.field_options(name):
+                errors.append(f"project field {name} options differ from the contract")
+        elif actual.get("dataType", "").lower() != expected.type.value:
+            errors.append(f"project field {name} type differs from the contract")
+
+    missing_items = open_work_urls(contract) - project_item_urls(contract)
+    for url in sorted(missing_items):
+        errors.append(f"project is missing open work item {url}")
+    errors.extend(label_drift(contract))
+    return EcosystemDrift(
+        errors=tuple(errors),
+        manual_controls=(
+            "Saved Project views must be compared in the GitHub UI.",
+            "Project auto-add, close, merge, and archive workflows must be compared in the GitHub UI.",
+        ),
+    )
+
+
+def apply_live(contract: EcosystemContract) -> None:
+    gh(
+        "project",
+        "edit",
+        str(contract.project.number),
+        "--owner",
+        contract.project.owner,
+        "--title",
+        contract.project.title,
+        "--visibility",
+        contract.project.visibility.value.upper(),
+        "--description",
+        contract.project.description,
+        "--readme",
+        contract.project_readme(),
+    )
+    linked = linked_repositories(contract)
+    for repository in contract.repositories():
+        if repository not in linked:
+            gh(
+                "project",
+                "link",
+                str(contract.project.number),
+                "--owner",
+                contract.project.owner,
+                "--repo",
+                repository,
+            )
+        for name, label in contract.labels.items():
+            gh(
+                "label",
+                "create",
+                name,
+                "--repo",
+                repository,
+                "--color",
+                label.color,
+                "--description",
+                label.description,
+                "--force",
+            )
+
+    existing_items = project_item_urls(contract)
+    for url in sorted(open_work_urls(contract) - existing_items):
+        gh(
+            "project",
+            "item-add",
+            str(contract.project.number),
+            "--owner",
+            contract.project.owner,
+            "--url",
+            url,
+        )
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(description="Validate and reconcile Modwire governance")
+    result.add_argument(
+        "command",
+        choices=("validate", "check-live", "apply-live", "schema"),
+        nargs="?",
+        default="validate",
+    )
+    result.add_argument("--contract", type=Path, default=DEFAULT_CONTRACT)
+    return result
+
+
+def main() -> int:
+    arguments = parser().parse_args()
+    contract = load_contract(arguments.contract)
+    if arguments.command == "schema":
+        print(json.dumps(EcosystemContract.model_json_schema(), indent=2))
+        return 0
+    if arguments.command == "validate":
+        errors = workflow_drift(contract)
+        if errors:
+            print(EcosystemDrift(errors=tuple(errors)).pretty())
+            return 1
+        print(
+            f"valid ecosystem contract: {len(contract.packages)} packages, "
+            f"{len(contract.fields)} project fields"
+        )
+        return 0
+    if arguments.command == "apply-live":
+        apply_live(contract)
+
+    drift = inspect_live(contract)
+    print(drift.pretty())
+    return 0 if drift.is_clean() else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

modwire-4.0.2/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  ecosystem-contract:
+    name: Ecosystem contract
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install coordinator
+        run: python -m pip install -e .
+      - name: Validate ecosystem contract
+        run: python .github/scripts/reconcile_ecosystem.py validate
+
+  verify:
+    uses: ./.github/workflows/python-package.yml

modwire-4.0.2/.github/workflows/python-package.yml

@@ -0,0 +1,84 @@
+name: Reusable Python package verification
+
+on:
+  workflow_call:
+    inputs:
+      python-versions:
+        description: JSON array of supported Python versions.
+        required: false
+        type: string
+        default: '["3.12", "3.13", "3.14"]'
+      build-python-version:
+        description: Python version used to build distributions once.
+        required: false
+        type: string
+        default: "3.12"
+      working-directory:
+        description: Package directory relative to the repository root.
+        required: false
+        type: string
+        default: "."
+      upload-artifacts:
+        description: Upload verified distributions for later jobs.
+        required: false
+        type: boolean
+        default: false
+      artifact-name:
+        description: Uploaded distribution artifact name.
+        required: false
+        type: string
+        default: python-package-distributions
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and verification tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest
+
+      - name: Run static checks
+        run: python -m ruff check .
+
+      - name: Build distributions
+        if: matrix.python-version == inputs.build-python-version
+        run: python -m build --outdir dist
+
+      - name: Check distribution metadata
+        if: matrix.python-version == inputs.build-python-version
+        run: python -m twine check dist/*
+
+      - name: Upload verified distributions
+        if: inputs.upload-artifacts && matrix.python-version == inputs.build-python-version
+        uses: actions/upload-artifact@v7
+        with:
+          name: ${{ inputs.artifact-name }}
+          path: ${{ inputs.working-directory }}/dist/
+          if-no-files-found: error