sdetkit 1.0.3__py3-none-any.whl

sdetkit/experiment_lane_37.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from ._legacy_lane import run_lane
+
+_DEFAULT_PAGE_TEMPLATE = "# Experiment lane\n\n## Experiment lane\n"
+_CFG = {
+    "name": "experiment-lane",
+    "page_path": "docs/integrations-experiment-lane.md",
+    "required_inputs": [
+        "docs/artifacts/distribution-closeout-pack/distribution-closeout-summary.json"
+    ],
+    "required_boards": ["docs/artifacts/distribution-closeout-pack/delivery-board.md"],
+    "summary_json": "experiment-lane-summary.json",
+    "summary_md": "experiment-lane-summary.md",
+    "pack_files": [
+        "experiment-matrix.csv",
+        "hypothesis-brief.md",
+        "experiment-scorecard.json",
+        "decision-log.md",
+        "delivery-board.md",
+        "validation-commands.md",
+    ],
+    "evidence_json": "execution-summary.json",
+    "text_output": " experiment lane summary",
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    return run_lane(argv, _CFG)

sdetkit/external_contribution.py

@@ -0,0 +1,463 @@
+from __future__ import annotations
+
+import argparse
+import json
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+_PAGE_PATH = "docs/external-contribution.md"
+_TOP10_PATH = "docs/top-10-github-strategy.md"
+_SECTION_HEADER = "# External contribution"
+_REQUIRED_SECTIONS = [
+    "## Who should run external-contribution",
+    "## Starter-task spotlight contract",
+    "## Launch checklist",
+    "## First-response SLA",
+    "## Activation scoring model",
+    "## Execution evidence mode",
+]
+_REQUIRED_COMMANDS = [
+    "python -m sdetkit external-contribution --format json --strict",
+    "python -m sdetkit external-contribution --emit-pack-dir docs/artifacts/external-contribution-pack --format json --strict",
+    "python -m sdetkit external-contribution --execute --evidence-dir docs/artifacts/external-contribution-pack/evidence --format json --strict",
+    "python scripts/check_external_contribution_contract.py",
+]
+_EXECUTION_COMMANDS = [
+    "python -m sdetkit external-contribution --format json --strict",
+    "python scripts/check_external_contribution_contract.py --skip-evidence",
+]
+
+_DEFAULT_PAGE_TEMPLATE = """# External contribution
+
+External contribution upgrades public contribution pull by spotlighting starter tasks with clear owners, response SLAs, and evidence-ready follow-up.
+
+## Who should run external-contribution
+
+- Maintainers who want more first-time external contributions from open starter tasks.
+- DevRel/community owners who promote contributor-friendly backlog slices.
+- Engineering leads that need deterministic response and conversion metrics.
+
+## Starter-task spotlight contract
+
+An external-contribution pass means at least 10 starter tasks are publicly spotlighted with labels, acceptance criteria, and explicit maintainer response windows.
+
+## Launch checklist
+
+```bash
+python -m sdetkit external-contribution --format json --strict
+python -m sdetkit external-contribution --emit-pack-dir docs/artifacts/external-contribution-pack --format json --strict
+python -m sdetkit external-contribution --execute --evidence-dir docs/artifacts/external-contribution-pack/evidence --format json --strict
+python scripts/check_external_contribution_contract.py
+```
+
+## First-response SLA
+
+- Respond to new external contribution comments within 24 hours.
+- Label every starter-task thread as `accepted`, `needs-info`, or `not-now`.
+- Publish weekly conversion summary (opened -> active -> merged).
+
+## Activation scoring model
+
+External-contribution computes a weighted readiness score (0-100):
+
+- Docs contract + command lane completeness: 45 points.
+- Discoverability links in README/docs index: 25 points.
+- Top-10 roadmap alignment + starter-task language: 20 points.
+- Evidence-lane readiness for strict validation: 10 points.
+
+## Execution evidence mode
+
+`--execute` runs deterministic external-contribution checks and writes logs to `--evidence-dir` for release review.
+"""
+
+_SIGNALS = [
+    {
+        "check_id": "docs_page_exists",
+        "category": "contract",
+        "weight": 15,
+        "evaluator": "page_exists",
+    },
+    {
+        "check_id": "required_sections_present",
+        "category": "contract",
+        "weight": 20,
+        "evaluator": "required_sections",
+    },
+    {
+        "check_id": "required_commands_present",
+        "category": "contract",
+        "weight": 10,
+        "evaluator": "required_commands",
+    },
+    {
+        "check_id": "readme_external_contribution_link",
+        "category": "discoverability",
+        "weight": 10,
+        "marker": "External contribution",
+        "source": "readme",
+    },
+    {
+        "check_id": "readme_external_contribution_command",
+        "category": "discoverability",
+        "weight": 8,
+        "marker": "external-contribution",
+        "source": "readme",
+    },
+    {
+        "check_id": "docs_index_external_contribution_link",
+        "category": "discoverability",
+        "weight": 7,
+        "marker": "docs/external-contribution.md",
+        "source": "docs_index",
+    },
+    {
+        "check_id": "top10_external_contribution_alignment",
+        "category": "strategy",
+        "weight": 10,
+        "marker": "External contribution",
+        "source": "top10",
+    },
+    {
+        "check_id": "docs_mentions_starter_tasks",
+        "category": "strategy",
+        "weight": 10,
+        "marker": "starter task",
+        "source": "page",
+    },
+    {
+        "check_id": "docs_mentions_response_sla",
+        "category": "evidence",
+        "weight": 10,
+        "marker": "24 hours",
+        "source": "page",
+    },
+]
+
+_CRITICAL_FAILURE_KEYS = {
+    "docs_page_exists",
+    "required_sections_present",
+    "required_commands_present",
+    "top10_external_contribution_alignment",
+}
+
+
+def _read(path: Path) -> str:
+    return path.read_text(encoding="utf-8") if path.exists() else ""
+
+
+def _evaluate_signals(
+    root: Path,
+    *,
+    page_text: str,
+    readme_text: str,
+    docs_index_text: str,
+    top10_text: str,
+) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    page_path = root / _PAGE_PATH
+
+    for signal in _SIGNALS:
+        evaluator = signal.get("evaluator")
+
+        if evaluator == "page_exists":
+            passed = page_path.exists()
+            evidence: Any = str(page_path)
+        elif evaluator == "required_sections":
+            missing = [
+                section
+                for section in [_SECTION_HEADER, *_REQUIRED_SECTIONS]
+                if section not in page_text
+            ]
+            passed = not missing
+            evidence = {"missing_sections": missing}
+        elif evaluator == "required_commands":
+            missing = [command for command in _REQUIRED_COMMANDS if command not in page_text]
+            passed = not missing
+            evidence = {"missing_commands": missing}
+        else:
+            marker = str(signal.get("marker", ""))
+            source = str(signal.get("source", "page"))
+            corpus = page_text
+            if source == "readme":
+                corpus = readme_text
+            elif source == "docs_index":
+                corpus = docs_index_text
+            elif source == "top10":
+                corpus = top10_text
+            passed = bool(marker) and marker in corpus
+            evidence = marker
+
+        rows.append(
+            {
+                "check_id": str(signal["check_id"]),
+                "category": str(signal["category"]),
+                "weight": int(str(signal["weight"])),
+                "passed": bool(passed),
+                "evidence": evidence,
+            }
+        )
+
+    return rows
+
+
+def build_external_contribution_summary(
+    root: Path,
+    *,
+    readme_path: str = "README.md",
+    docs_index_path: str = "docs/index.md",
+    docs_page_path: str = _PAGE_PATH,
+    top10_path: str = _TOP10_PATH,
+) -> dict[str, Any]:
+    checks = _evaluate_signals(
+        root,
+        page_text=_read(root / docs_page_path),
+        readme_text=_read(root / readme_path),
+        docs_index_text=_read(root / docs_index_path),
+        top10_text=_read(root / top10_path),
+    )
+
+    total_weight = sum(int(item["weight"]) for item in checks)
+    earned_weight = sum(int(item["weight"]) for item in checks if item["passed"])
+    score = round((earned_weight / total_weight) * 100, 2) if total_weight else 0.0
+
+    failed = [item for item in checks if not item["passed"]]
+    critical_failures = [
+        item["check_id"] for item in failed if item["check_id"] in _CRITICAL_FAILURE_KEYS
+    ]
+
+    recommendations: list[str] = []
+    if any(item["category"] == "contract" for item in failed):
+        recommendations.append(
+            "Restore external-contribution docs contract sections and required command lane before launch."
+        )
+    if any(item["category"] == "discoverability" for item in failed):
+        recommendations.append(
+            "Add external-contribution links and commands to README/docs index for external contributor visibility."
+        )
+    if any(item["category"] in {"strategy", "evidence"} for item in failed):
+        recommendations.append(
+            "Align external-contribution outputs with starter-task spotlighting and 24-hour first-response SLA."
+        )
+    if not recommendations:
+        recommendations.append(
+            "External-contribution lane is healthy; keep weekly conversion summaries flowing."
+        )
+
+    return {
+        "name": "external-contribution",
+        "inputs": {
+            "readme": readme_path,
+            "docs_index": docs_index_path,
+            "docs_page": docs_page_path,
+            "top10": top10_path,
+        },
+        "checks": checks,
+        "summary": {
+            "activation_score": score,
+            "total_checks": len(checks),
+            "failed_checks": [item["check_id"] for item in failed],
+            "critical_failures": critical_failures,
+            "recommendations": recommendations,
+        },
+    }
+
+
+def _render_text(payload: dict[str, Any]) -> str:
+    lines = [
+        "External contribution summary",
+        f"score={payload['summary']['activation_score']}",
+        f"failed={','.join(payload['summary']['failed_checks']) or 'none'}",
+        f"critical={','.join(payload['summary']['critical_failures']) or 'none'}",
+        "",
+        "Checks:",
+    ]
+    for item in payload["checks"]:
+        lines.append(
+            f"- [{'x' if item['passed'] else ' '}] {item['check_id']} ({item['category']}, w={item['weight']})"
+        )
+    return "\n".join(lines)
+
+
+def emit_pack(root: Path, out_dir: Path, payload: dict[str, Any]) -> list[str]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    summary = out_dir / "external-contribution-summary.json"
+    scorecard = out_dir / "external-contribution-scorecard.md"
+    spotlight = out_dir / "external-contribution-starter-task-spotlight.md"
+    triage = out_dir / "external-contribution-triage-board.md"
+    validation = out_dir / "external-contribution-validation-commands.md"
+
+    summary.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    scorecard.write_text(_render_text(payload) + "\n", encoding="utf-8")
+    spotlight.write_text(
+        "\n".join(
+            [
+                "# External contribution starter-task spotlight",
+                "",
+                "## Public call-to-action",
+                "Help wanted: pick one starter task and submit your first contribution this week.",
+                "",
+                "## Spotlight checklist",
+                "- [ ] Link top 10 starter tasks with acceptance criteria.",
+                "- [ ] Assign maintainer owner for each task.",
+                "- [ ] Include setup prerequisites and expected completion time.",
+                "",
+                "## Promotion channels",
+                "1. GitHub discussion",
+                "2. X / LinkedIn post",
+                "3. Community Discord/Slack announcement",
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    triage.write_text(
+        "\n".join(
+            [
+                "# External contribution triage board",
+                "",
+                "| Starter task | Interest signal | Owner | Status | Response SLA |",
+                "| --- | --- | --- | --- | --- |",
+                "| Example: docs quickstart polish | 0 comments | @owner | needs-info | <=24h |",
+                "",
+                "First-response SLA: acknowledge every external contributor within 24 hours.",
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    validation.write_text(
+        "\n".join(
+            [
+                "# External contribution validation commands",
+                "",
+                "```bash",
+                *_REQUIRED_COMMANDS,
+                "```",
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+    return [
+        str(path.relative_to(root)) for path in [summary, scorecard, spotlight, triage, validation]
+    ]
+
+
+def execute_commands(root: Path, evidence_dir: Path, timeout_sec: int) -> dict[str, Any]:
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+    results: list[dict[str, Any]] = []
+    for command in _EXECUTION_COMMANDS:
+        argv = shlex.split(command)
+        if argv and argv[0] == "python":
+            argv[0] = sys.executable
+        proc = subprocess.run(argv, cwd=root, text=True, capture_output=True, timeout=timeout_sec)
+        results.append(
+            {
+                "command": command,
+                "returncode": proc.returncode,
+                "stdout": proc.stdout,
+                "stderr": proc.stderr,
+            }
+        )
+    payload = {
+        "name": "external-contribution-execution",
+        "total_commands": len(_EXECUTION_COMMANDS),
+        "results": results,
+    }
+    (evidence_dir / "external-contribution-execution-summary.json").write_text(
+        json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    return payload
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sdetkit external-contribution",
+        description="External-contribution rollout lane.",
+    )
+    parser.add_argument("--root", default=".", help="Repository root path.")
+    parser.add_argument(
+        "--readme", default="README.md", help="README path for discoverability checks."
+    )
+    parser.add_argument(
+        "--docs-index", default="docs/index.md", help="Docs index path for discoverability checks."
+    )
+    parser.add_argument("--top10", default=_TOP10_PATH, help="Top-10 roadmap strategy path.")
+    parser.add_argument(
+        "--write-defaults", action="store_true", help="Create default external-contribution page."
+    )
+    parser.add_argument(
+        "--emit-pack-dir",
+        default="",
+        help="Optional output directory for generated external-contribution files.",
+    )
+    parser.add_argument(
+        "--execute",
+        action="store_true",
+        help="Run external-contribution command chain and emit evidence logs.",
+    )
+    parser.add_argument(
+        "--evidence-dir",
+        default="docs/artifacts/external-contribution-pack/evidence",
+        help="Output directory for execution evidence logs.",
+    )
+    parser.add_argument(
+        "--timeout-sec", type=int, default=120, help="Per-command timeout used by --execute."
+    )
+    parser.add_argument(
+        "--min-score", type=float, default=90.0, help="Minimum score for strict pass."
+    )
+    parser.add_argument(
+        "--strict", action="store_true", help="Fail when score or critical checks are not ready."
+    )
+    parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format.")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    ns = build_parser().parse_args(argv)
+    root = Path(ns.root).resolve()
+    page = root / _PAGE_PATH
+
+    if ns.write_defaults:
+        page.parent.mkdir(parents=True, exist_ok=True)
+        page.write_text(_DEFAULT_PAGE_TEMPLATE, encoding="utf-8")
+
+    payload = build_external_contribution_summary(
+        root,
+        readme_path=ns.readme,
+        docs_index_path=ns.docs_index,
+        top10_path=ns.top10,
+    )
+    page_text = _read(page)
+    missing_sections = [
+        section for section in [_SECTION_HEADER, *_REQUIRED_SECTIONS] if section not in page_text
+    ]
+    missing_commands = [command for command in _REQUIRED_COMMANDS if command not in page_text]
+    payload["strict_failures"] = [*missing_sections, *missing_commands]
+
+    if ns.emit_pack_dir:
+        payload["emitted_pack_files"] = emit_pack(root, root / ns.emit_pack_dir, payload)
+    if ns.execute:
+        payload["execution"] = execute_commands(root, root / ns.evidence_dir, ns.timeout_sec)
+
+    strict_failed = (
+        bool(payload["strict_failures"])
+        or payload["summary"]["activation_score"] < ns.min_score
+        or bool(payload["summary"]["critical_failures"])
+    )
+
+    if ns.format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(_render_text(payload))
+
+    return 1 if ns.strict and strict_failed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sdetkit/feature_registry.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .public_surface_contract import PUBLIC_SURFACE_CONTRACT
+
+_REQUIRED_FIELDS = {
+    "command",
+    "tier",
+    "status",
+    "problem_solved",
+    "example",
+    "expected_output",
+    "test_file",
+    "docs_page",
+}
+_ALLOWED_TIERS = {"A", "B", "C"}
+_ALLOWED_STATUSES = {"stable", "advanced", "experimental"}
+_DOC_TABLE_START = "<!-- feature-registry:table:start -->"
+_DOC_TABLE_END = "<!-- feature-registry:table:end -->"
+
+
+@dataclass(frozen=True)
+class FeatureEntry:
+    command: str
+    tier: str
+    status: str
+    problem_solved: str
+    example: str
+    expected_output: str
+    test_file: str
+    docs_page: str
+
+
+def _registry_path() -> Path:
+    return Path(__file__).resolve().parent / "data" / "feature_registry.json"
+
+
+def _known_top_level_commands() -> set[str]:
+    commands: set[str] = set()
+    for family in PUBLIC_SURFACE_CONTRACT:
+        commands.update(family.top_level_commands)
+    return commands
+
+
+def load_feature_registry() -> list[FeatureEntry]:
+    payload = json.loads(_registry_path().read_text(encoding="utf-8"))
+    if not isinstance(payload, list):
+        raise ValueError("feature registry must be a list")
+
+    rows: list[FeatureEntry] = []
+    seen: set[str] = set()
+    for i, item in enumerate(payload, start=1):
+        if not isinstance(item, dict):
+            raise ValueError(f"feature registry item #{i} must be an object")
+        missing = sorted(_REQUIRED_FIELDS - set(item))
+        if missing:
+            raise ValueError(f"feature registry item #{i} missing fields: {', '.join(missing)}")
+
+        entry = FeatureEntry(
+            command=str(item["command"]).strip(),
+            tier=str(item["tier"]).strip(),
+            status=str(item["status"]).strip(),
+            problem_solved=str(item["problem_solved"]).strip(),
+            example=str(item["example"]).strip(),
+            expected_output=str(item["expected_output"]).strip(),
+            test_file=str(item["test_file"]).strip(),
+            docs_page=str(item["docs_page"]).strip(),
+        )
+        if not entry.command:
+            raise ValueError(f"feature registry item #{i} has empty command")
+        if entry.command in seen:
+            raise ValueError(f"feature registry duplicate command: {entry.command}")
+        seen.add(entry.command)
+        rows.append(entry)
+
+    return rows
+
+
+def _table_line(item: FeatureEntry) -> str:
+    return (
+        f"| `{item.command}` | {item.tier} | {item.status} | {item.problem_solved} | "
+        f"`{item.example}` | [{item.test_file}]({item.test_file}) | [{item.docs_page}]({item.docs_page}) |"
+    )
+
+
+def render_feature_registry_table(rows: list[FeatureEntry]) -> str:
+    lines = [
+        "| Command | Tier | Status | Problem solved | Example | Test | Docs |",
+        "| --- | --- | --- | --- | --- | --- | --- |",
+    ]
+    lines.extend(_table_line(item) for item in sorted(rows, key=lambda x: (x.tier, x.command)))
+    return "\n".join(lines)
+
+
+def render_feature_registry_docs_block(rows: list[FeatureEntry]) -> str:
+    lines = [
+        "| Command | Tier | Status | Problem solved | Example | Test | Docs |",
+        "| --- | --- | --- | --- | --- | --- | --- |",
+    ]
+    for item in sorted(rows, key=lambda x: (x.tier, x.command)):
+        docs_link = item.docs_page.removeprefix("docs/")
+        lines.append(
+            f"| `{item.command}` | {item.tier} | {item.status} | {item.problem_solved} | "
+            f"`{item.example}` | `{item.test_file}` | [{item.docs_page}]({docs_link}) |"
+        )
+    table = "\n".join(lines)
+    return f"{_DOC_TABLE_START}\n{table}\n{_DOC_TABLE_END}"
+
+
+def summarize_feature_registry(rows: list[FeatureEntry]) -> dict[str, object]:
+    by_tier: dict[str, int] = {}
+    by_status: dict[str, int] = {}
+    commands: list[str] = []
+    for item in sorted(rows, key=lambda x: x.command):
+        by_tier[item.tier] = by_tier.get(item.tier, 0) + 1
+        by_status[item.status] = by_status.get(item.status, 0) + 1
+        commands.append(item.command)
+    return {
+        "total": len(rows),
+        "by_tier": by_tier,
+        "by_status": by_status,
+        "commands": commands,
+    }
+
+
+def ensure_feature_registry_docs_synced(repo_root: Path) -> list[str]:
+    docs_path = repo_root / "docs" / "feature-registry.md"
+    if not docs_path.exists():
+        return ["feature-registry docs page is missing"]
+
+    text = docs_path.read_text(encoding="utf-8")
+    start = text.find(_DOC_TABLE_START)
+    end = text.find(_DOC_TABLE_END)
+    if start == -1 or end == -1 or end < start:
+        return ["feature-registry docs markers are missing or malformed"]
+
+    end += len(_DOC_TABLE_END)
+    current = text[start:end].strip()
+    expected = render_feature_registry_docs_block(load_feature_registry()).strip()
+    if current != expected:
+        return ["feature-registry docs table is stale; run scripts/sync_feature_registry_docs.py"]
+    return []
+
+
+def validate_feature_registry_contract(repo_root: Path) -> list[str]:
+    errors: list[str] = []
+    known_commands = _known_top_level_commands()
+
+    for item in load_feature_registry():
+        if item.tier not in _ALLOWED_TIERS:
+            errors.append(f"{item.command}: tier must be one of {_ALLOWED_TIERS}")
+        if item.status not in _ALLOWED_STATUSES:
+            errors.append(f"{item.command}: status must be one of {_ALLOWED_STATUSES}")
+        if not item.example.startswith("python -m sdetkit"):
+            errors.append(f"{item.command}: example must start with 'python -m sdetkit'")
+        if item.command not in known_commands:
+            errors.append(f"{item.command}: command is not in the public surface contract")
+        if item.tier == "A" and item.status != "stable":
+            errors.append(f"{item.command}: tier A commands must use stable status")
+
+        test_path = repo_root / item.test_file
+        if not test_path.exists():
+            errors.append(f"{item.command}: missing test file: {item.test_file}")
+
+        docs_path = repo_root / item.docs_page
+        if not docs_path.exists():
+            errors.append(f"{item.command}: missing docs page: {item.docs_page}")
+
+    errors.extend(ensure_feature_registry_docs_synced(repo_root))
+    return errors