maintainer-readiness-kit 0.6.1__py3-none-any.whl

maintainer_readiness/__init__.py

@@ -0,0 +1,4 @@
+"""Maintainer readiness reporting for open source repositories."""
+
+__all__ = ["__version__"]
+__version__ = "0.6.1"

maintainer_readiness/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

maintainer_readiness/badge.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+def render_badge(result: dict) -> dict:
+    percent = float(result.get("percent", 0.0))
+    if percent >= 90:
+        color = "brightgreen"
+    elif percent >= 70:
+        color = "yellow"
+    else:
+        color = "red"
+    return {
+        "schemaVersion": 1,
+        "label": "maintainer readiness",
+        "message": f"{percent:.1f}%",
+        "color": color,
+    }

maintainer_readiness/checks.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from pathlib import Path
+import subprocess
+from typing import Iterable
+
+
+@dataclass(frozen=True)
+class CheckSpec:
+    check_id: str
+    label: str
+    weight: int
+    candidates: tuple[str, ...]
+    fix: str
+
+
+CHECKS: tuple[CheckSpec, ...] = (
+    CheckSpec("readme", "README explains purpose and usage", 12, ("README.md", "README.rst"), "Add a README with install, quick start, and limitations."),
+    CheckSpec("license", "Open source license is present", 12, ("LICENSE", "LICENSE.md", "COPYING"), "Add a recognized open source license."),
+    CheckSpec("contributing", "Contributor guide is present", 8, ("CONTRIBUTING.md", "docs/CONTRIBUTING.md"), "Add CONTRIBUTING.md with setup and contribution flow."),
+    CheckSpec("security", "Security policy is present", 10, ("SECURITY.md", ".github/SECURITY.md"), "Add SECURITY.md with supported versions and disclosure contact."),
+    CheckSpec("code_of_conduct", "Code of conduct is present", 5, ("CODE_OF_CONDUCT.md", ".github/CODE_OF_CONDUCT.md"), "Add a code of conduct or link to the community standard."),
+    CheckSpec("issue_template", "Issue template is present", 8, (".github/ISSUE_TEMPLATE",), "Add bug and feature issue templates."),
+    CheckSpec("pr_template", "Pull request template is present", 8, (".github/PULL_REQUEST_TEMPLATE.md", "PULL_REQUEST_TEMPLATE.md"), "Add a pull request template with test and risk prompts."),
+    CheckSpec("ci", "Continuous integration workflow is present", 10, (".github/workflows",), "Add a minimal CI workflow that runs tests or smoke checks."),
+    CheckSpec("tests", "Tests are present", 10, ("tests", "test"), "Add a small test suite or smoke test directory."),
+    CheckSpec("manifest", "Package or project manifest is present", 8, ("pyproject.toml", "package.json", "go.mod", "Cargo.toml", "pom.xml"), "Add a package manifest or project metadata file."),
+    CheckSpec("docs", "Docs or examples are present", 5, ("docs", "examples"), "Add docs or examples for contributors and users."),
+    CheckSpec("changelog", "Changelog or release notes are present", 4, ("CHANGELOG.md", "RELEASES.md", "docs/releases.md"), "Add a changelog or release notes file."),
+)
+
+
+HIGH_RISK_NAMES = {
+    ".env",
+    ".env.local",
+    ".env.production",
+    ".npmrc",
+    ".pypirc",
+    "credentials.json",
+    "service-account.json",
+    "id_rsa",
+    "id_ed25519",
+}
+
+
+@dataclass(frozen=True)
+class EcosystemRule:
+    ecosystem: str
+    evidence: tuple[str, ...]
+    recommendations: tuple[str, ...]
+
+
+ECOSYSTEM_RULES: tuple[EcosystemRule, ...] = (
+    EcosystemRule(
+        "python",
+        ("pyproject.toml", "requirements.txt", "setup.py", "setup.cfg"),
+        (
+            "Run `python -m unittest discover -s tests` or the documented test command in CI.",
+            "Keep packaging metadata in `pyproject.toml` and publish wheels from tagged releases.",
+            "Use `src/` layout or clear package discovery to avoid importing local files accidentally.",
+            "Document supported Python versions and minimum dependency policy.",
+        ),
+    ),
+    EcosystemRule(
+        "node",
+        ("package.json", "pnpm-lock.yaml", "package-lock.json", "yarn.lock"),
+        (
+            "Expose `npm test` or an equivalent package script and run it in CI.",
+            "Commit one lockfile for apps, or document why libraries avoid lockfiles.",
+            "Document supported Node.js versions in README or package metadata.",
+            "Run a package audit or dependency review before releases.",
+        ),
+    ),
+    EcosystemRule(
+        "rust",
+        ("Cargo.toml", "Cargo.lock"),
+        (
+            "Run `cargo test` and `cargo clippy` in CI.",
+            "Document supported Rust toolchain or MSRV.",
+            "Commit `Cargo.lock` for binaries and document lockfile policy for libraries.",
+            "Keep release notes aligned with crate version changes.",
+        ),
+    ),
+    EcosystemRule(
+        "go",
+        ("go.mod", "go.sum"),
+        (
+            "Run `go test ./...` in CI.",
+            "Keep `go.mod` and `go.sum` committed and tidy.",
+            "Document supported Go version and module path.",
+            "Use tagged releases for module consumers.",
+        ),
+    ),
+    EcosystemRule(
+        "java",
+        ("pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle"),
+        (
+            "Run Maven or Gradle tests in CI.",
+            "Document the supported Java version and build tool version.",
+            "Keep dependency update and vulnerability review policy clear.",
+            "Align release notes with package or artifact versions.",
+        ),
+    ),
+)
+
+
+@dataclass
+class CheckResult:
+    check_id: str
+    label: str
+    passed: bool
+    weight: int
+    evidence: str
+    fix: str
+
+
+def inspect_project(root: Path | str, root_label: str | None = None) -> dict:
+    root_path = Path(root).resolve()
+    check_results = [run_check(root_path, spec) for spec in CHECKS]
+    score = sum(item.weight for item in check_results if item.passed)
+    max_score = sum(item.weight for item in check_results)
+    percent = round((score / max_score) * 100, 1) if max_score else 0.0
+    return {
+        "root": str(root_path),
+        "display_root": root_label or str(root_path),
+        "score": score,
+        "max_score": max_score,
+        "percent": percent,
+        "level": classify_level(percent),
+        "checks": [asdict(item) for item in check_results],
+        "ecosystems": detect_ecosystems(root_path),
+        "git": get_git_metrics(root_path),
+        "secret_warnings": find_high_risk_files(root_path),
+    }
+
+
+def classify_level(percent: float) -> str:
+    if percent >= 90:
+        return "ready"
+    if percent >= 70:
+        return "nearly-ready"
+    return "needs-work"
+
+
+def run_check(root: Path, spec: CheckSpec) -> CheckResult:
+    evidence = find_first_existing(root, spec.candidates)
+    return CheckResult(
+        check_id=spec.check_id,
+        label=spec.label,
+        passed=evidence is not None,
+        weight=spec.weight,
+        evidence=evidence or "missing",
+        fix=spec.fix,
+    )
+
+
+def find_first_existing(root: Path, candidates: Iterable[str]) -> str | None:
+    for candidate in candidates:
+        path = root / candidate
+        if path.exists():
+            if path.is_dir():
+                child_count = sum(1 for _ in path.iterdir())
+                if child_count == 0:
+                    continue
+            return candidate
+    return None
+
+
+def detect_ecosystems(root: Path) -> list[dict]:
+    detected: list[dict] = []
+    for rule in ECOSYSTEM_RULES:
+        evidence = [candidate for candidate in rule.evidence if (root / candidate).exists()]
+        if evidence:
+            detected.append(
+                {
+                    "ecosystem": rule.ecosystem,
+                    "evidence": evidence,
+                    "recommendations": list(rule.recommendations),
+                }
+            )
+    if not detected:
+        detected.append(
+            {
+                "ecosystem": "generic",
+                "evidence": [],
+                "recommendations": [
+                    "Document the primary runtime, test command, and release process.",
+                    "Add a CI smoke check that exercises the project entry point.",
+                    "Include examples that show the smallest useful workflow.",
+                ],
+            }
+        )
+    return detected
+
+
+def get_git_metrics(root: Path) -> dict:
+    if not (root / ".git").exists():
+        inside = _git(root, "rev-parse", "--is-inside-work-tree")
+        if inside.returncode != 0 or inside.stdout.strip() != "true":
+            return {"available": False, "reason": "not a git repository"}
+
+    branch = _git(root, "rev-parse", "--abbrev-ref", "HEAD")
+    last_commit = _git(root, "log", "-1", "--format=%cI")
+    count_90 = _git(root, "rev-list", "--count", "--since=90.days.ago", "HEAD")
+    dirty = _git(root, "status", "--short")
+    return {
+        "available": last_commit.returncode == 0,
+        "branch": branch.stdout.strip() if branch.returncode == 0 else None,
+        "last_commit": last_commit.stdout.strip() if last_commit.returncode == 0 else None,
+        "commits_last_90_days": _parse_int(count_90.stdout.strip()) if count_90.returncode == 0 else None,
+        "dirty_files": len([line for line in dirty.stdout.splitlines() if line.strip()]) if dirty.returncode == 0 else None,
+    }
+
+
+def find_high_risk_files(root: Path) -> list[dict]:
+    warnings: list[dict] = []
+    ignored = {".git", ".venv", "venv", "__pycache__", "dist", "build"}
+    for path in root.rglob("*"):
+        if any(part in ignored for part in path.parts):
+            continue
+        if path.is_file() and path.name in HIGH_RISK_NAMES:
+            warnings.append(
+                {
+                    "path": str(path.relative_to(root)),
+                    "reason": "high-risk local credential/config filename",
+                }
+            )
+    return warnings
+
+
+def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=str(root),
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+
+
+def _parse_int(value: str) -> int | None:
+    try:
+        return int(value)
+    except ValueError:
+        return None

maintainer_readiness/cli.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from . import __version__
+from .checks import inspect_project
+from .badge import render_badge
+from .github import fetch_github_repo
+from .report import render_markdown
+from .sarif import render_sarif
+from .templates import write_templates
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="maintainer-readiness",
+        description="Generate maintainer-readiness reports for OSS repositories.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    inspect_parser = subparsers.add_parser("inspect", help="Inspect a repository.")
+    inspect_parser.add_argument("path", nargs="?", default=".", help="Repository path to inspect.")
+    inspect_parser.add_argument("--repo", help="Optional GitHub repo as owner/name or URL.")
+    inspect_parser.add_argument("--output", help="Write Markdown report to this path.")
+    inspect_parser.add_argument("--sarif", help="Write SARIF report to this path.")
+    inspect_parser.add_argument("--badge-json", help="Write Shields endpoint JSON to this path.")
+    inspect_parser.add_argument("--root-label", help="Display label to use instead of the absolute local root path.")
+    inspect_parser.add_argument("--json", action="store_true", help="Print JSON instead of Markdown.")
+    inspect_parser.add_argument(
+        "--stale-days",
+        type=int,
+        default=30,
+        metavar="DAYS",
+        help="Treat open GitHub issues and pull requests as stale after DAYS without updates.",
+    )
+    inspect_parser.add_argument(
+        "--fail-under",
+        type=float,
+        metavar="SCORE",
+        help="Exit non-zero when the readiness percentage is below SCORE.",
+    )
+
+    init_parser = subparsers.add_parser("init", help="Write starter maintainer templates.")
+    init_parser.add_argument("path", nargs="?", default=".", help="Repository path to initialize.")
+    init_parser.add_argument("--force", action="store_true", help="Overwrite existing starter files.")
+    init_parser.add_argument("--json", action="store_true", help="Print JSON output.")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "inspect":
+        return run_inspect(args)
+    if args.command == "init":
+        return run_init(args)
+    parser.error("unknown command")
+    return 2
+
+
+def run_inspect(args: argparse.Namespace) -> int:
+    if args.stale_days <= 0:
+        raise SystemExit("--stale-days must be a positive integer")
+    result = inspect_project(args.path, root_label=args.root_label)
+    github = None
+    if args.repo:
+        github = fetch_github_repo(args.repo, stale_days=args.stale_days)
+    exit_code = readiness_exit_code(result, args.fail_under)
+    if args.sarif:
+        sarif_path = Path(args.sarif)
+        sarif_path.parent.mkdir(parents=True, exist_ok=True)
+        sarif_path.write_text(json.dumps(render_sarif(result, github), ensure_ascii=False, indent=2), encoding="utf-8", newline="\n")
+    if args.badge_json:
+        badge_path = Path(args.badge_json)
+        badge_path.parent.mkdir(parents=True, exist_ok=True)
+        badge_path.write_text(json.dumps(render_badge(result), ensure_ascii=False, indent=2), encoding="utf-8", newline="\n")
+
+    if args.json:
+        payload = {"readiness": result, "github": github}
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return exit_code
+
+    markdown = render_markdown(result, github)
+    if args.output:
+        output_path = Path(args.output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(markdown, encoding="utf-8", newline="\n")
+        print(f"Wrote {output_path}")
+    else:
+        print(markdown)
+    return exit_code
+
+
+def readiness_exit_code(result: dict, fail_under: float | None) -> int:
+    if fail_under is None:
+        return 0
+    if fail_under < 0 or fail_under > 100:
+        raise SystemExit("--fail-under must be between 0 and 100")
+    return 1 if result["percent"] < fail_under else 0
+
+
+def run_init(args: argparse.Namespace) -> int:
+    result = write_templates(args.path, force=args.force)
+    if args.json:
+        print(json.dumps({"templates": result}, ensure_ascii=False, indent=2))
+    else:
+        for item in result:
+            print(f"{item['status']}: {item['path']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

maintainer_readiness/github.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+import json
+import os
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+def fetch_github_repo(repo: str, token: str | None = None, stale_days: int = 30) -> dict:
+    normalized = repo.strip().removeprefix("https://github.com/").strip("/")
+    if normalized.count("/") != 1:
+        raise ValueError("repo must be owner/name or https://github.com/owner/name")
+
+    auth_token = token or os.environ.get("GITHUB_TOKEN")
+    payload = _github_get_json(f"https://api.github.com/repos/{normalized}", auth_token, normalized)
+    try:
+        open_items = _github_get_json(
+            f"https://api.github.com/repos/{normalized}/issues?state=open&per_page=100&sort=updated&direction=asc",
+            auth_token,
+            normalized,
+        )
+        workload = summarize_open_items(open_items, stale_days=stale_days)
+    except RuntimeError as exc:
+        workload = {"activity_error": str(exc)}
+
+    return {
+        "full_name": payload.get("full_name"),
+        "html_url": payload.get("html_url"),
+        "description": payload.get("description"),
+        "visibility": payload.get("visibility"),
+        "stars": payload.get("stargazers_count"),
+        "forks": payload.get("forks_count"),
+        "open_issues": payload.get("open_issues_count"),
+        "created_at": payload.get("created_at"),
+        "updated_at": payload.get("updated_at"),
+        "pushed_at": payload.get("pushed_at"),
+        "default_branch": payload.get("default_branch"),
+        **workload,
+    }
+
+
+def _github_get_json(url: str, auth_token: str | None, repo_label: str) -> dict | list[dict]:
+    request = Request(url)
+    request.add_header("Accept", "application/vnd.github+json")
+    if auth_token:
+        request.add_header("Authorization", f"Bearer {auth_token}")
+
+    try:
+        with urlopen(request, timeout=15) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except HTTPError as exc:
+        raise RuntimeError(f"GitHub API returned HTTP {exc.code} for {repo_label}") from exc
+    except URLError as exc:
+        raise RuntimeError(f"GitHub API request failed for {repo_label}: {exc.reason}") from exc
+
+
+def summarize_open_items(items: list[dict], now: datetime | None = None, stale_days: int = 30) -> dict:
+    if stale_days <= 0:
+        raise ValueError("stale_days must be positive")
+    now = now or datetime.now(timezone.utc)
+    cutoff = now - timedelta(days=stale_days)
+    issues = []
+    pulls = []
+    for item in items:
+        updated_at = _parse_github_datetime(item.get("updated_at"))
+        if updated_at is None:
+            continue
+        if item.get("pull_request"):
+            pulls.append(updated_at)
+        else:
+            issues.append(updated_at)
+
+    return {
+        "activity_sample_limit": 100,
+        "stale_days": stale_days,
+        "open_issue_items_sampled": len(issues),
+        "open_pr_items_sampled": len(pulls),
+        "stale_issue_items": sum(updated_at < cutoff for updated_at in issues),
+        "stale_pr_items": sum(updated_at < cutoff for updated_at in pulls),
+        "oldest_open_issue_updated_at": _oldest_iso(issues),
+        "oldest_open_pr_updated_at": _oldest_iso(pulls),
+    }
+
+
+def _parse_github_datetime(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _oldest_iso(values: list[datetime]) -> str | None:
+    if not values:
+        return None
+    return min(values).isoformat(timespec="seconds").replace("+00:00", "Z")

maintainer_readiness/report.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def render_markdown(result: dict, github: dict | None = None) -> str:
+    lines: list[str] = []
+    lines.append("# Maintainer Readiness Report")
+    lines.append("")
+    lines.append(f"- Generated: {datetime.now(timezone.utc).isoformat(timespec='seconds')}")
+    lines.append(f"- Root: `{result.get('display_root', result['root'])}`")
+    lines.append(f"- Score: **{result['score']} / {result['max_score']}** ({result['percent']}%)")
+    lines.append(f"- Level: **{result['level']}**")
+    lines.append("")
+
+    if github:
+        lines.append("## Public GitHub Signals")
+        lines.append("")
+        lines.append(f"- Repository: [{github.get('full_name')}]({github.get('html_url')})")
+        lines.append(f"- Visibility: `{github.get('visibility')}`")
+        lines.append(f"- Stars: `{github.get('stars')}`")
+        lines.append(f"- Forks: `{github.get('forks')}`")
+        lines.append(f"- Open issues: `{github.get('open_issues')}`")
+        lines.append(f"- Last push: `{github.get('pushed_at')}`")
+        if github.get("activity_error"):
+            lines.append(f"- Open issue/PR activity: unavailable ({github.get('activity_error')})")
+        elif github.get("stale_days") is not None:
+            lines.append(
+                f"- Open issues sampled: `{github.get('open_issue_items_sampled')}` "
+                f"(`{github.get('stale_issue_items')}` stale over {github.get('stale_days')} days)"
+            )
+            lines.append(
+                f"- Open PRs sampled: `{github.get('open_pr_items_sampled')}` "
+                f"(`{github.get('stale_pr_items')}` stale over {github.get('stale_days')} days)"
+            )
+            if github.get("oldest_open_issue_updated_at"):
+                lines.append(f"- Oldest open issue update: `{github.get('oldest_open_issue_updated_at')}`")
+            if github.get("oldest_open_pr_updated_at"):
+                lines.append(f"- Oldest open PR update: `{github.get('oldest_open_pr_updated_at')}`")
+        lines.append("")
+
+    git = result.get("git", {})
+    lines.append("## Local Maintenance Signals")
+    lines.append("")
+    if git.get("available"):
+        lines.append(f"- Branch: `{git.get('branch')}`")
+        lines.append(f"- Last commit: `{git.get('last_commit')}`")
+        lines.append(f"- Commits in last 90 days: `{git.get('commits_last_90_days')}`")
+        lines.append(f"- Dirty files: `{git.get('dirty_files')}`")
+    else:
+        lines.append(f"- Git metadata unavailable: {git.get('reason', 'unknown')}")
+    lines.append("")
+
+    passed = [item for item in result["checks"] if item["passed"]]
+    missing = [item for item in result["checks"] if not item["passed"]]
+    lines.append("## Passing Signals")
+    lines.append("")
+    for item in passed:
+        lines.append(f"- {item['label']}: `{item['evidence']}` (+{item['weight']})")
+    if not passed:
+        lines.append("- None yet.")
+    lines.append("")
+
+    lines.append("## Missing Signals")
+    lines.append("")
+    for item in missing:
+        lines.append(f"- {item['label']}: {item['fix']} (+{item['weight']})")
+    if not missing:
+        lines.append("- None.")
+    lines.append("")
+
+    lines.append("## Ecosystem Recommendations")
+    lines.append("")
+    for item in result.get("ecosystems", []):
+        evidence = ", ".join(f"`{value}`" for value in item.get("evidence", [])) or "no manifest detected"
+        lines.append(f"### {item['ecosystem'].title()}")
+        lines.append("")
+        lines.append(f"- Evidence: {evidence}")
+        for recommendation in item.get("recommendations", []):
+            lines.append(f"- {recommendation}")
+        lines.append("")
+
+    warnings = result.get("secret_warnings", [])
+    lines.append("## High-Risk File Warnings")
+    lines.append("")
+    if warnings:
+        for warning in warnings:
+            lines.append(f"- `{warning['path']}`: {warning['reason']}")
+    else:
+        lines.append("- No high-risk credential filenames found.")
+    lines.append("")
+
+    lines.append("## Maintainer Program Notes")
+    lines.append("")
+    lines.append("- Use this report as evidence, not as a guarantee of eligibility.")
+    lines.append("- Do not claim usage, adoption, or maintainer permissions that cannot be verified.")
+    lines.append("- For new repositories, describe the project as early-stage and explain the concrete maintainer workflow it supports.")
+    lines.append("- Keep human approval in the loop for issue triage, PR review, releases, and public communication.")
+    lines.append("")
+    return "\n".join(lines)

maintainer_readiness/sarif.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def render_sarif(result: dict, github: dict | None = None) -> dict:
+    rules = []
+    sarif_results = []
+    for item in result.get("checks", []):
+        rule_id = f"maintainer-readiness.{item['check_id']}"
+        rules.append(
+            {
+                "id": rule_id,
+                "name": item["label"],
+                "shortDescription": {"text": item["label"]},
+                "help": {"text": item["fix"]},
+                "properties": {"weight": item["weight"]},
+            }
+        )
+        if not item.get("passed"):
+            sarif_results.append(
+                {
+                    "ruleId": rule_id,
+                    "level": "warning",
+                    "message": {"text": item["fix"]},
+                    "locations": [_location(result, item.get("evidence") or ".")],
+                }
+            )
+
+    rules.append(
+        {
+            "id": "maintainer-readiness.high-risk-file",
+            "name": "High-risk credential filename",
+            "shortDescription": {"text": "High-risk credential filename"},
+            "help": {"text": "Remove local credential/config files before publishing the repository."},
+        }
+    )
+    for warning in result.get("secret_warnings", []):
+        sarif_results.append(
+            {
+                "ruleId": "maintainer-readiness.high-risk-file",
+                "level": "error",
+                "message": {"text": warning["reason"]},
+                "locations": [_location(result, warning["path"])],
+            }
+        )
+
+    if github and github.get("stale_issue_items"):
+        rules.append(_github_rule("stale-issues", "Stale open issues"))
+        sarif_results.append(_github_result("stale-issues", f"{github['stale_issue_items']} open issues are stale."))
+    if github and github.get("stale_pr_items"):
+        rules.append(_github_rule("stale-prs", "Stale open pull requests"))
+        sarif_results.append(_github_result("stale-prs", f"{github['stale_pr_items']} open pull requests are stale."))
+
+    return {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "Maintainer Readiness Kit",
+                        "informationUri": "https://github.com/YUUDAI-s/maintainer-readiness-kit",
+                        "rules": rules,
+                    }
+                },
+                "invocations": [
+                    {
+                        "executionSuccessful": True,
+                        "endTimeUtc": datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z"),
+                    }
+                ],
+                "results": sarif_results,
+            }
+        ],
+    }
+
+
+def _location(result: dict, path: str) -> dict:
+    display_root = result.get("display_root") or result.get("root") or "."
+    artifact = "." if path == "missing" else path
+    return {
+        "physicalLocation": {
+            "artifactLocation": {
+                "uri": artifact,
+                "uriBaseId": display_root,
+            }
+        }
+    }
+
+
+def _github_rule(suffix: str, name: str) -> dict:
+    return {
+        "id": f"maintainer-readiness.github.{suffix}",
+        "name": name,
+        "shortDescription": {"text": name},
+        "help": {"text": "Review stale public GitHub work as part of routine maintainer triage."},
+    }
+
+
+def _github_result(suffix: str, message: str) -> dict:
+    return {
+        "ruleId": f"maintainer-readiness.github.{suffix}",
+        "level": "note",
+        "message": {"text": message},
+    }

maintainer_readiness/templates.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+TEMPLATES: dict[str, str] = {
+    "CONTRIBUTING.md": """# Contributing
+
+Thanks for helping improve this project.
+
+## Local Setup
+
+1. Fork and clone the repository.
+2. Install the documented runtime.
+3. Run the smoke test or unit tests before opening a pull request.
+
+## Pull Requests
+
+- Keep changes focused.
+- Include tests or a manual verification note.
+- Document behavior changes in the README or changelog when relevant.
+""",
+    "SECURITY.md": """# Security Policy
+
+## Supported Versions
+
+The default branch receives security fixes.
+
+## Reporting a Vulnerability
+
+Please open a private security advisory or contact the maintainer through the
+repository owner profile. Do not disclose exploitable details publicly before a
+fix or mitigation is available.
+""",
+    ".github/ISSUE_TEMPLATE/bug_report.yml": """name: Bug report
+description: Report a reproducible bug.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Reproduction steps
+      description: List the smallest steps that reproduce the issue.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, version, runtime, and any relevant config.
+""",
+    ".github/ISSUE_TEMPLATE/feature_request.yml": """name: Feature request
+description: Suggest an improvement.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem would this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: Describe the smallest useful change.
+""",
+    ".github/PULL_REQUEST_TEMPLATE.md": """## Summary
+
+## Verification
+
+- [ ] Tests or smoke checks were run.
+- [ ] Documentation was updated, or no docs change is needed.
+- [ ] Security/privacy impact was considered.
+
+## Notes for Maintainers
+""",
+    ".github/workflows/maintainer-readiness.yml": """name: Maintainer readiness
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m unittest
+""",
+}
+
+
+def write_templates(root: Path | str, force: bool = False) -> list[dict]:
+    root_path = Path(root).resolve()
+    written: list[dict] = []
+    for relative_path, content in TEMPLATES.items():
+        target = root_path / relative_path
+        if target.exists() and not force:
+            written.append({"path": relative_path, "status": "skipped"})
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8", newline="\n")
+        written.append({"path": relative_path, "status": "written"})
+    return written

maintainer_readiness_kit-0.6.1.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: maintainer-readiness-kit
+Version: 0.6.1
+Summary: Generate maintainer-readiness reports for open source repositories.
+Author: YUUDAI-s
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YUUDAI-s/maintainer-readiness-kit
+Project-URL: Repository, https://github.com/YUUDAI-s/maintainer-readiness-kit
+Project-URL: Issues, https://github.com/YUUDAI-s/maintainer-readiness-kit/issues
+Keywords: open-source,maintainer,github,security,triage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Maintainer Readiness Kit
+
+[![Maintainer readiness](https://github.com/YUUDAI-s/maintainer-readiness-kit/actions/workflows/maintainer-readiness.yml/badge.svg)](https://github.com/YUUDAI-s/maintainer-readiness-kit/actions/workflows/maintainer-readiness.yml)
+[![GitHub Action](https://img.shields.io/badge/GitHub%20Action-ready-brightgreen.svg)](action.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](pyproject.toml)
+
+Maintainer Readiness Kit is a small, dependency-light CLI that audits an open
+source repository for maintainer-facing signals: documentation, license files,
+security policy, issue and pull request templates, CI, tests, recent git
+activity, and high-risk local secret files.
+
+The goal is simple: give solo and small-team maintainers a repeatable report
+they can use before publishing a repository, onboarding contributors, or asking
+for support from open source maintainer programs.
+
+## Who Should Use It
+
+- Maintainers preparing a repository for public contributors.
+- Solo developers who need a concrete pre-release checklist.
+- Teams that want CI to fail when maintainer basics regress.
+- Open source applicants who need honest, shareable evidence instead of vague
+  claims.
+
+## What It Helps You Decide
+
+Use it when you need a quick answer to:
+
+- Is this repository ready to make public?
+- What maintainer files are missing before I invite contributors?
+- Will CI fail if the repository falls below a readiness threshold?
+- What ecosystem-specific maintenance steps should I add next?
+- Can I share a report without leaking my local machine path?
+
+## Features
+
+- Scores maintainer-readiness signals with evidence and suggested fixes.
+- Reads local git activity without requiring network access.
+- Optionally enriches the report with public GitHub repository signals.
+- Summarizes stale open issues and pull requests for public GitHub reports.
+- Generates starter maintainer templates for `CONTRIBUTING.md`,
+  `SECURITY.md`, issue templates, pull request templates, and a GitHub Actions
+  smoke workflow.
+- Performs a conservative high-risk file check before public release.
+- Outputs Markdown or JSON for CI and handoff docs.
+- Outputs SARIF for CI and code-scanning workflows.
+- Outputs Shields endpoint badge JSON for project dashboards.
+- Runs as a reusable GitHub Action.
+- Classifies readiness as `ready`, `nearly-ready`, or `needs-work`.
+- Detects Python, Node.js, Rust, Go, and Java/JVM manifests and adds
+  ecosystem-specific maintainer recommendations.
+
+## Quick Start
+
+Install from the repository:
+
+```powershell
+git clone https://github.com/YUUDAI-s/maintainer-readiness-kit.git
+cd maintainer-readiness-kit
+python -m pip install -e .
+maintainer-readiness inspect . --output readiness-report.md
+maintainer-readiness inspect . --fail-under 90
+```
+
+Use it directly in GitHub Actions:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: YUUDAI-s/maintainer-readiness-kit@v0.6.0
+    with:
+      repo: owner/name
+      fail-under: "80"
+      output: readiness-report.md
+      sarif: readiness.sarif
+      badge-json: readiness-badge.json
+```
+
+Public demo repository:
+[`YUUDAI-s/maintainer-readiness-kit-action-demo`](https://github.com/YUUDAI-s/maintainer-readiness-kit-action-demo)
+uses `YUUDAI-s/maintainer-readiness-kit@v0.6.0` in CI.
+
+After the package is published to PyPI:
+
+```powershell
+python -m pip install maintainer-readiness-kit
+maintainer-readiness inspect . --output readiness-report.md
+```
+
+For local source development without installation:
+
+```powershell
+$env:PYTHONPATH = "src"
+python -m maintainer_readiness inspect . --output readiness-report.md
+python -m maintainer_readiness inspect . --fail-under 90
+```
+
+Typical output:
+
+```text
+Score: 100 / 100 (100.0%)
+Level: ready
+Ecosystem Recommendations: Python
+High-Risk File Warnings: No high-risk credential filenames found.
+```
+
+To include public GitHub signals:
+
+```powershell
+python -m maintainer_readiness inspect . --repo YUUDAI-s/maintainer-readiness-kit --output readiness-report.md
+```
+
+To add starter maintainer files to another repository:
+
+```powershell
+python -m maintainer_readiness init C:\path\to\repo
+```
+
+Use `--force` only when you intentionally want to overwrite an existing starter
+file.
+
+## Commands
+
+### `inspect`
+
+```powershell
+python -m maintainer_readiness inspect . --output readiness-report.md
+python -m maintainer_readiness inspect . --json
+python -m maintainer_readiness inspect . --repo owner/name
+python -m maintainer_readiness inspect . --root-label public-sample
+python -m maintainer_readiness inspect . --repo owner/name --stale-days 14
+python -m maintainer_readiness inspect . --sarif readiness.sarif
+python -m maintainer_readiness inspect . --badge-json readiness-badge.json
+```
+
+The Markdown report includes:
+
+- overall readiness score,
+- readiness level,
+- passing and missing signals,
+- local git maintenance evidence,
+- optional public GitHub evidence,
+- stale open issue and pull request counts when `--repo` is used,
+- high-risk file warnings,
+- ecosystem-specific recommendations,
+- next actions before public release.
+
+For CI, use `--fail-under` to make the command return a non-zero exit code when
+the readiness percentage is below your chosen threshold.
+
+Use `--stale-days` with `--repo` when your project has a shorter or longer
+triage window than the default 30 days.
+
+Use `--sarif readiness.sarif` when you want failed checks and high-risk file
+warnings in a code-scanning compatible format.
+
+Use `--badge-json readiness-badge.json` when you want a Shields-compatible
+endpoint JSON payload for a dashboard or docs site.
+
+### GitHub Actions
+
+```yaml
+name: Maintainer readiness
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: YUUDAI-s/maintainer-readiness-kit@v0.6.0
+        with:
+          repo: owner/name
+          fail-under: "80"
+          output: readiness-report.md
+          sarif: readiness.sarif
+          badge-json: readiness-badge.json
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: readiness.sarif
+```
+
+### `init`
+
+```powershell
+python -m maintainer_readiness init .
+```
+
+This writes starter maintainer files only when they do not already exist:
+
+- `CONTRIBUTING.md`
+- `SECURITY.md`
+- `MAINTAINERS.md`
+- `.github/ISSUE_TEMPLATE/bug_report.yml`
+- `.github/ISSUE_TEMPLATE/feature_request.yml`
+- `.github/PULL_REQUEST_TEMPLATE.md`
+- `.github/workflows/maintainer-readiness.yml`
+
+## Design Principles
+
+- Honest evidence over vanity metrics.
+- Minimal runtime dependencies.
+- Useful defaults for maintainers who work alone.
+- No external writes from `inspect`.
+- No claims that a repository qualifies for any external program.
+
+## Maintainer Workflows
+
+This project is built for routine maintainer tasks:
+
+- pre-publication checks before making a repository public,
+- contributor onboarding checks before accepting outside PRs,
+- release-readiness checks before tagging a version,
+- safety checks before attaching reports to sponsorship or maintainer-support
+  applications,
+- CI-friendly JSON output for repeatable repository hygiene reviews.
+
+## Limitations
+
+This tool cannot prove that a repository is widely adopted, safe, or eligible
+for any benefit. It only turns common maintainer signals into a compact,
+verifiable report. Program applications still require accurate information
+about the applicant, repository, role, usage, and maintainer status.
+
+## Development
+
+```powershell
+$env:PYTHONPATH = "src"
+python -m unittest discover -s tests
+python -m maintainer_readiness inspect . --output readiness-report.md
+```
+
+See [ROADMAP.md](ROADMAP.md) for near-term maintainer-focused work.
+See [examples/reports](examples/reports) for generated reports from real
+repositories.
+See the public action demo at
+[YUUDAI-s/maintainer-readiness-kit-action-demo](https://github.com/YUUDAI-s/maintainer-readiness-kit-action-demo).
+See [docs/pypi.md](docs/pypi.md) for package build and publishing notes.
+See [docs/community-launch.md](docs/community-launch.md) for community launch
+copy and posting rules.
+See [examples/github-action.yml](examples/github-action.yml) for a copyable
+GitHub Actions workflow.
+
+## License
+
+MIT

maintainer_readiness_kit-0.6.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+maintainer_readiness/__init__.py,sha256=d7z5SbcgKnhdJ_1PjcK0syEAV_NfBXAcbXZ_fb4edYA,116
+maintainer_readiness/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+maintainer_readiness/badge.py,sha256=_EpBYi4iacavwhjWi2cYTybQxXXlLGGXTyyb3yoQAVM,408
+maintainer_readiness/checks.py,sha256=oKvb10CUUSoJWL9Khh4EOAEOgu_UeTL0cf-dhRkJZT4,9424
+maintainer_readiness/cli.py,sha256=cgDh0aHyIln8W-HCQjJyCRmKrcjtN-FMAaieQ-qdyIs,4637
+maintainer_readiness/github.py,sha256=UfQc7gSg4KqKLIH_4Rp_dFhfgdpUxfnvh0F5aAKqzCo,3692
+maintainer_readiness/report.py,sha256=5w6DRG4d4k8JIye4cbJjVQD0VDxAU_DAwE747KF_-ho,4615
+maintainer_readiness/sarif.py,sha256=hmZSOGcC2dq2BQHs4CZJePTPgFGbLsOyj_afw8oq4Ac,3708
+maintainer_readiness/templates.py,sha256=1LZaApzcr2y0FYltxRc9DklDz48ylIaoGtnxBS-6jkE,3090
+maintainer_readiness_kit-0.6.1.dist-info/licenses/LICENSE,sha256=3Av74KsPftReiKqDpDz_NOXQTqx-r_pDyYwkQumHnv0,1065
+maintainer_readiness_kit-0.6.1.dist-info/METADATA,sha256=LdqmUycwKwLONEyWplcYLavbmoGC9SmBtKmtMDDnUyk,9383
+maintainer_readiness_kit-0.6.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+maintainer_readiness_kit-0.6.1.dist-info/entry_points.txt,sha256=9lIWav-AHLQQWHss0cPoAsjpQrJCUTU0TVK2GdbDMb4,71
+maintainer_readiness_kit-0.6.1.dist-info/top_level.txt,sha256=4RcbzRmQd6_4ogZSvUrlrE9uUC8mMJLieeL0QlqguEc,21
+maintainer_readiness_kit-0.6.1.dist-info/RECORD,,

maintainer_readiness_kit-0.6.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

maintainer_readiness_kit-0.6.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+maintainer-readiness = maintainer_readiness.cli:main

maintainer_readiness_kit-0.6.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YUUDAI-s
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maintainer_readiness_kit-0.6.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+maintainer_readiness