pubfleet 0.2.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,144 @@
1
+ """The github connector: the GitHub REST API, for what a repository is
2
+ and holds (its visibility, pubrules.json, release.json, lock and workflow
3
+ files, rulesets, releases, open issues) and its security alerts.
4
+
5
+ It reads with one token, sent only to api.github.com. A refused or
6
+ missing read is a Fact with no value and GitHub's reason as its note.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import base64
12
+ import binascii
13
+
14
+ from .base import Connector, Fact, Ledger, Transport
15
+
16
+ API = "https://api.github.com"
17
+ # Pages of 100 read for a count before it is reported as "at least".
18
+ PAGES = 10
19
+
20
+
21
+ def headers(token: str | None) -> dict[str, str]:
22
+ out = {"Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28",
23
+ "User-Agent": "pubfleet-board"}
24
+ if token:
25
+ out["Authorization"] = f"Bearer {token}"
26
+ return out
27
+
28
+
29
+ class GitHub(Connector):
30
+ name = "github"
31
+
32
+ def __init__(self, ledger: Ledger, transport: Transport, token: str | None = None):
33
+ super().__init__(ledger, transport, headers(token))
34
+
35
+ def repository(self, repo: str) -> Fact:
36
+ """Visibility, default branch, whether it is archived, and the status of
37
+ secret scanning and push protection, which GitHub shows only to a token with
38
+ Administration read."""
39
+ response, call = self.get("repository", f"{API}/repos/{repo}")
40
+ if not response.ok:
41
+ return Fact(None, (call,), response.message())
42
+ data = response.json()
43
+ security = data.get("security_and_analysis")
44
+ return Fact({"security": None if security is None else {
45
+ name: (security.get(name) or {}).get("status")
46
+ for name in ("secret_scanning", "secret_scanning_push_protection")},
47
+ "visibility": data.get("visibility") or
48
+ ("private" if data.get("private") else "public"),
49
+ "default_branch": data.get("default_branch", "main"),
50
+ "archived": bool(data.get("archived"))}, (call,))
51
+
52
+ def _file(self, method: str, repo: str, path: str) -> Fact:
53
+ """A file's text on the default branch; None, noted, when absent."""
54
+ response, call = self.get(method, f"{API}/repos/{repo}/contents/{path}")
55
+ if response.status == 404:
56
+ return Fact(None, (call,), f"no {path}")
57
+ if not response.ok:
58
+ return Fact(None, (call,), response.message())
59
+ data = response.json()
60
+ if not isinstance(data, dict) or data.get("type", "file") != "file" or "content" not in data:
61
+ return Fact(None, (call,), f"{path} is not a file")
62
+ try:
63
+ return Fact(base64.b64decode(data["content"]).decode("utf-8"), (call,))
64
+ except (binascii.Error, ValueError, UnicodeDecodeError) as e:
65
+ return Fact(None, (call,), f"{path} could not be decoded ({e})")
66
+
67
+ def pubrules_json(self, repo: str) -> Fact:
68
+ return self._file("pubrules_json", repo, "pubrules.json")
69
+
70
+ def release_json(self, repo: str) -> Fact:
71
+ return self._file("release_json", repo, "release.json")
72
+
73
+ def requirements_lock(self, repo: str) -> Fact:
74
+ return self._file("requirements_lock", repo, "tests/requirements.lock")
75
+
76
+ def workflow(self, repo: str, name: str) -> Fact:
77
+ return self._file("workflow", repo, f".github/workflows/{name}")
78
+
79
+ def workflow_names(self, repo: str) -> Fact:
80
+ """The file names in .github/workflows."""
81
+ response, call = self.get("workflow_names", f"{API}/repos/{repo}/contents/.github/workflows")
82
+ if response.status == 404:
83
+ return Fact([], (call,), "no .github/workflows")
84
+ if not response.ok:
85
+ return Fact(None, (call,), response.message())
86
+ listed = response.json()
87
+ return Fact(sorted(f["name"] for f in listed if isinstance(f, dict)
88
+ and f.get("type") == "file"), (call,))
89
+
90
+ def rulesets(self, repo: str) -> Fact:
91
+ """The repository's own rulesets, each in full."""
92
+ response, call = self.get("rulesets",
93
+ f"{API}/repos/{repo}/rulesets?includes_parents=false")
94
+ if not response.ok:
95
+ return Fact(None, (call,), response.message())
96
+ calls, out = [call], []
97
+ for listed in response.json() or []:
98
+ one, one_call = self.get("ruleset", f"{API}/repos/{repo}/rulesets/{listed['id']}")
99
+ calls.append(one_call)
100
+ if not one.ok:
101
+ return Fact(None, tuple(calls), one.message())
102
+ out.append(one.json())
103
+ return Fact(out, tuple(calls))
104
+
105
+ def latest_release(self, repo: str) -> Fact:
106
+ """The newest published release: its tag and when it was published."""
107
+ response, call = self.get("latest_release", f"{API}/repos/{repo}/releases?per_page=10")
108
+ if not response.ok:
109
+ return Fact(None, (call,), response.message())
110
+ published = [r for r in response.json() or [] if not r.get("draft") and r.get("published_at")]
111
+ if not published:
112
+ return Fact(None, (call,), "GitHub has no published release")
113
+ newest = max(published, key=lambda r: r["published_at"])
114
+ return Fact({"tag": newest["tag_name"], "at": newest["published_at"]}, (call,))
115
+
116
+ def _count(self, method: str, url: str, keep=lambda item: True) -> Fact:
117
+ """How many items a listing has, page by page."""
118
+ calls, total = [], 0
119
+ for page in range(1, PAGES + 1):
120
+ response, call = self.get(method, f"{url}&per_page=100&page={page}")
121
+ calls.append(call)
122
+ if not response.ok:
123
+ return Fact(None, tuple(calls), response.message())
124
+ items = response.json() or []
125
+ total += sum(1 for item in items if keep(item))
126
+ if len(items) < 100:
127
+ return Fact(total, tuple(calls))
128
+ return Fact(total, tuple(calls), f"at least {total}: stopped after {PAGES} pages")
129
+
130
+ def open_issues(self, repo: str) -> Fact:
131
+ """Open issues; pull requests, which GitHub lists with them, are not counted."""
132
+ return self._count("open_issues", f"{API}/repos/{repo}/issues?state=open",
133
+ lambda item: "pull_request" not in item)
134
+
135
+ def dependabot_alerts(self, repo: str) -> Fact:
136
+ return self._count("dependabot_alerts", f"{API}/repos/{repo}/dependabot/alerts?state=open")
137
+
138
+ def code_scanning_alerts(self, repo: str) -> Fact:
139
+ return self._count("code_scanning_alerts",
140
+ f"{API}/repos/{repo}/code-scanning/alerts?state=open")
141
+
142
+ def secret_scanning_alerts(self, repo: str) -> Fact:
143
+ return self._count("secret_scanning_alerts",
144
+ f"{API}/repos/{repo}/secret-scanning/alerts?state=open")
@@ -0,0 +1,17 @@
1
+ """The live connector: the services themselves, over HTTPS, at the
2
+ health URL each declares in its pubrules.json."""
3
+
4
+ from __future__ import annotations
5
+
6
+ from .base import Connector, Fact
7
+
8
+
9
+ class Live(Connector):
10
+ name = "live"
11
+
12
+ def health(self, url: str) -> Fact:
13
+ """Whether the URL answers with a success, and its status."""
14
+ response, call = self.get("health", url)
15
+ if response.error:
16
+ return Fact({"answers": False, "status": None}, (call,), response.error)
17
+ return Fact({"answers": response.ok, "status": response.status}, (call,))
@@ -0,0 +1,23 @@
1
+ """The repos connector: a repos file, which says which repositories the board grades."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+
7
+ from pubrules.repos import entries
8
+
9
+ from .base import Connector, Fact
10
+
11
+
12
+ class Repos(Connector):
13
+ name = "repos"
14
+
15
+ def listed(self, path: Path) -> Fact:
16
+ """A repos file's entries: each repository and its roles."""
17
+ response, call = self.get("listed", f"file:{path}", f"file:{path.name}")
18
+ if not response.ok:
19
+ return Fact(None, (call,), response.message())
20
+ try:
21
+ return Fact(entries(response.body or b"", path.name), (call,))
22
+ except ValueError as e:
23
+ return Fact(None, (call,), str(e))
@@ -0,0 +1,24 @@
1
+ """The scorecard connector: the OpenSSF Scorecard API, for a public
2
+ repository's score out of 10 and the checks scoring under it."""
3
+
4
+ from __future__ import annotations
5
+
6
+ from .base import Connector, Fact
7
+
8
+ API = "https://api.securityscorecards.dev"
9
+
10
+
11
+ class Scorecard(Connector):
12
+ name = "scorecard"
13
+
14
+ def score(self, repo: str) -> Fact:
15
+ """The score and the checks below 10; None when Scorecard has not scored it."""
16
+ response, call = self.get("score", f"{API}/projects/github.com/{repo}")
17
+ if response.status == 404 or (response.ok and not response.body.strip()):
18
+ return Fact(None, (call,), "not scored by OpenSSF Scorecard")
19
+ if not response.ok:
20
+ return Fact(None, (call,), response.message())
21
+ data = response.json() or {}
22
+ failing = sorted(c["name"] for c in data.get("checks", [])
23
+ if isinstance(c.get("score"), int | float) and 0 <= c["score"] < 10)
24
+ return Fact({"score": data.get("score"), "failing": failing}, (call,))
@@ -0,0 +1,52 @@
1
+ """The sonarcloud connector: SonarQube Cloud's Web API, for a project's
2
+ reliability, maintainability and security ratings and its quality gate.
3
+
4
+ pubrules' CI names a repository's project OWNER_REPO. A public project
5
+ needs no token; SONAR_TOKEN, when set, reads a private one.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from .base import Connector, Fact, Ledger, Transport
11
+
12
+ API = "https://sonarcloud.io/api"
13
+ METRICS = {"reliability_rating": "reliability", "sqale_rating": "maintainability",
14
+ "security_rating": "security", "alert_status": "gate"}
15
+ LETTERS = "ABCDE"
16
+
17
+
18
+ def project(repo: str) -> str:
19
+ return repo.replace("/", "_")
20
+
21
+
22
+ class SonarCloud(Connector):
23
+ name = "sonarcloud"
24
+
25
+ def __init__(self, ledger: Ledger, transport: Transport, token: str | None = None):
26
+ super().__init__(ledger, transport,
27
+ {"Authorization": f"Bearer {token}"} if token else {})
28
+
29
+ def ratings(self, repo: str) -> Fact:
30
+ """Each rating as a letter, A to E, and the gate, OK or ERROR;
31
+ None when SonarQube Cloud has no analysis of the project."""
32
+ response, call = self.get(
33
+ "ratings", f"{API}/measures/component?component={project(repo)}"
34
+ f"&metricKeys={','.join(METRICS)}")
35
+ if response.status == 404:
36
+ return Fact(None, (call,), f"no SonarQube Cloud project {project(repo)}")
37
+ if not response.ok:
38
+ return Fact(None, (call,), response.message())
39
+ measures = {m["metric"]: m.get("value")
40
+ for m in (response.json() or {}).get("component", {}).get("measures", [])}
41
+ out = {}
42
+ for metric, name in METRICS.items():
43
+ value = measures.get(metric)
44
+ if value is None:
45
+ continue
46
+ if metric == "alert_status":
47
+ out[name] = value
48
+ else:
49
+ out[name] = LETTERS[min(max(round(float(value)), 1), 5) - 1]
50
+ if not {"reliability", "maintainability", "security"} <= out.keys():
51
+ return Fact(None, (call,), f"SonarQube Cloud project {project(repo)} has no ratings yet")
52
+ return Fact(out, (call,))
pubfleet/board/page.py ADDED
@@ -0,0 +1,125 @@
1
+ """The board as one static HTML page: no scripts, no requests.
2
+
3
+ Each grade is a dot in SonarQube's A to E colours. Hovering it, or
4
+ tabbing to it, opens its breakdown: the start, each notch, and the
5
+ connector call each rests on. Rows come worst first.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from html import escape
11
+
12
+ STYLE = """
13
+ :root{--bg:#f6f7f5;--surface:#fff;--fg:#1b2420;--muted:#5b6862;--line:#dde3df;--accent:#1f6b5c;
14
+ --gA:#2e9e4f;--gB:#8cc63f;--gC:#e6c229;--gD:#f08c2e;--gE:#d9473b;--ink:#1b2420;color-scheme:light}
15
+ @media (prefers-color-scheme:dark){:root:not([data-theme="light"]){--bg:#121816;--surface:#1a2220;
16
+ --fg:#e4ebe7;--muted:#9aa8a1;--line:#2c3632;--accent:#6cc4ae;color-scheme:dark}}
17
+ :root[data-theme="dark"]{--bg:#121816;--surface:#1a2220;--fg:#e4ebe7;--muted:#9aa8a1;--line:#2c3632;
18
+ --accent:#6cc4ae;color-scheme:dark}
19
+ *{box-sizing:border-box}
20
+ body{margin:0;background:var(--bg);color:var(--fg);
21
+ font:15px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
22
+ main{max-width:1100px;margin:0 auto;padding:32px 16px 64px;display:flex;flex-direction:column;gap:16px}
23
+ h1{margin:0;font-size:28px}
24
+ p{margin:0}
25
+ .meta,.tag,.src{color:var(--muted);font-size:13px}
26
+ .problems{color:var(--gE)}
27
+ .wrap{background:var(--surface);border:1px solid var(--line);border-radius:10px}
28
+ table{border-collapse:collapse;width:100%}
29
+ th,td{text-align:left;padding:10px 12px;border-bottom:1px solid var(--line);vertical-align:middle}
30
+ th{font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:var(--muted)}
31
+ tbody>tr:last-child>td{border-bottom:0}
32
+ td.mono{font-family:ui-monospace,Menlo,monospace;font-size:13px;white-space:nowrap}
33
+ .dot{display:inline-grid;place-items:center;width:24px;height:24px;border-radius:50%;
34
+ font:600 12px/1 ui-monospace,Menlo,monospace;color:#fff}
35
+ .A{background:var(--gA)}.E{background:var(--gE)}
36
+ .B{background:var(--gB);color:var(--ink)}.C{background:var(--gC);color:var(--ink)}.D{background:var(--gD);color:var(--ink)}
37
+ .overall .dot{width:30px;height:30px;font-size:14px}
38
+ .grade{position:relative;display:inline-block;border-radius:50%;cursor:default}
39
+ .grade:focus-visible{outline:2px solid var(--accent);outline-offset:3px}
40
+ .pop{display:none;position:absolute;z-index:2;top:calc(100% + 6px);right:-8px;width:min(460px,86vw);
41
+ background:var(--surface);border:1px solid var(--line);border-radius:8px;padding:10px 12px;
42
+ box-shadow:0 6px 24px rgb(0 0 0/.18)}
43
+ .grade:hover .pop,.grade:focus .pop,.grade:focus-within .pop{display:block}
44
+ .pop table{width:100%}
45
+ .pop td{padding:4px 6px;border-bottom:1px solid var(--line);font-size:13px;white-space:normal;
46
+ vertical-align:top}
47
+ .pop tr:last-child td{border-bottom:0;font-weight:600}
48
+ .pop td.n{white-space:nowrap;font-family:ui-monospace,Menlo,monospace}
49
+ @media (max-width:760px){
50
+ .wrap>table>thead{display:none}
51
+ .wrap>table>tbody>tr{display:grid;grid-template-columns:repeat(3,1fr);gap:6px 12px;padding:12px;
52
+ border-bottom:1px solid var(--line)}
53
+ .wrap>table>tbody>tr>td{border:0;padding:0}
54
+ .wrap>table>tbody>tr>td:first-child{grid-column:1/-1;white-space:normal}
55
+ .wrap>table>tbody>tr>td[data-label]::before{content:attr(data-label);display:block;font-size:11px;
56
+ color:var(--muted);text-transform:uppercase;letter-spacing:.06em}
57
+ .pop{position:fixed;top:auto;left:16px;right:16px;bottom:16px;width:auto;max-height:70vh;overflow-y:auto}
58
+ }
59
+ """
60
+
61
+
62
+ def source_label(step: dict, calls: dict[str, dict]) -> str:
63
+ """The connectors and methods a step rests on: "github · issues, rulesets"."""
64
+ methods: dict[str, list[str]] = {}
65
+ for source in step.get("sources", []):
66
+ call = calls.get(source)
67
+ connector, method = (call["connector"], call["method"]) if call else ("call", source)
68
+ if method not in methods.setdefault(connector, []):
69
+ methods[connector].append(method)
70
+ return "; ".join(f"{c} · {', '.join(m)}" for c, m in methods.items()) or \
71
+ ", ".join(f"fact {f}" for f in step.get("facts", []))
72
+
73
+
74
+ def breakdown(name: str, grade: dict, calls: dict[str, dict], ident: str) -> str:
75
+ start = grade["start"]
76
+ rows = [f"<tr><td>{escape(start['text'])}</td><td class=n><span class=\"dot {start['letter']}\">"
77
+ f"{start['letter']}</span></td><td class=src>{escape(source_label(start, calls))}</td></tr>"]
78
+ for step in grade["steps"]:
79
+ delta = "−1" if step["delta"] < 0 else "note"
80
+ rows.append(f"<tr><td>{escape(step['text'])}</td><td class=n>{delta}</td>"
81
+ f"<td class=src>{escape(source_label(step, calls))}</td></tr>")
82
+ rows.append(f"<tr><td>{escape(name)}</td><td class=n><span class=\"dot {grade['letter']}\">"
83
+ f"{grade['letter']}</span></td><td class=src>{grade['notches']} notch"
84
+ f"{'es' if grade['notches'] != 1 else ''}</td></tr>")
85
+ return (f"<span class=grade tabindex=0 aria-describedby={ident}>"
86
+ f"<span class=\"dot {grade['letter']}\" aria-label=\"{escape(name)} {grade['letter']}\">"
87
+ f"{grade['letter']}</span><span class=pop role=tooltip id={ident}><table><tbody>"
88
+ f"{''.join(rows)}</tbody></table></span></span>")
89
+
90
+
91
+ def render(board: dict) -> str:
92
+ calls = {c["id"]: c for c in board["calls"]}
93
+ rows = []
94
+ for n, row in enumerate(board["repos"]):
95
+ private = " <span class=tag>private</span>" if row["visibility"] == "private" else ""
96
+ cells = "".join(
97
+ f"<td data-label={label}>{breakdown(label, row['grades'][key], calls, f'r{n}-{key[0]}')}</td>"
98
+ for key, label in (("quality", "Quality"), ("security", "Security"),
99
+ ("delivery", "Delivery")))
100
+ overall = row["overall"]
101
+ project = f" <span class=tag>{escape(row['project'])}</span>" if row.get("project") else ""
102
+ rows.append(
103
+ f"<tr><td class=mono>{escape(row['repo'])}{private}{project} <span class=tag>{row['kind']}</span></td>"
104
+ f"<td class=overall data-label=Overall><span class=\"dot {overall}\">{overall}</span></td>"
105
+ f"<td class=mono data-label=Released>{escape(row['released'])}</td>"
106
+ f"<td class=mono data-label=pubrules>{escape(row['pubrules'])}</td>"
107
+ f"{cells}</tr>")
108
+ problems = "".join(f"<p class=problems>{escape(p)}</p>" for p in board.get("problems", []))
109
+ return f"""<!doctype html>
110
+ <html lang=en><head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1">
111
+ <title>Release board</title><style>{STYLE}</style></head>
112
+ <body><main>
113
+ <h1>Release board</h1>
114
+ <p>{escape(board['summary'])}</p>
115
+ <p class=meta>Graded by pubrules {escape(board['pubrules'])} with the rules "{escape(board['rules'])}".
116
+ Hover or tab to a grade for how it was reached; board.json has every reading.</p>
117
+ {problems}
118
+ <div class=wrap><table>
119
+ <thead><tr><th>Repository</th><th>Overall</th><th>Released</th><th>pubrules</th><th>Quality</th>
120
+ <th>Security</th><th>Delivery</th></tr></thead>
121
+ <tbody>
122
+ {chr(10).join(rows)}
123
+ </tbody></table></div>
124
+ </main></body></html>
125
+ """
@@ -0,0 +1,37 @@
1
+ {
2
+ "comment": "The rules `pubfleet board` grades repositories by (rules.py says how each is applied). Each row gets three grades, A to E. Quality starts at SonarQube Cloud's worse rating of reliability and maintainability, Security at its security rating; with no analysis, each starts at A and takes the sonar notch. Then each tool below with findings takes one letter off its category's grade: a CI job on main's last run that failed, or open alerts, or a Scorecard score under `below`. Delivery starts at A and takes one letter for each notch in `delivery` that applies (to all, packages or services) and finds a gap. A grade never goes below E, but every notch is listed. The overall grade is the worst of the three. Drop an entry to drop its notch; `pubfleet board --rules FILE` reads another file. `workflows` and `repositories` tell the board where to look: which workflow files are CI, nightly and deploy, and which repositories release pubrules and pubrel.",
3
+ "name": "pubrules 2026-10",
4
+ "sonar": "No SonarQube Cloud analysis",
5
+ "tools": [
6
+ { "tool": "format and lint", "category": "quality", "jobs": ["gates", "lint"], "covers": "rustfmt, clippy, ruff, eslint, doc coverage" },
7
+ { "tool": "tests", "category": "quality", "jobs": ["test", "tests"] },
8
+ { "tool": "functional tests", "category": "quality", "jobs": ["functional"] },
9
+ { "tool": "browser tests", "category": "quality", "jobs": ["browser"] },
10
+ { "tool": "MSRV", "category": "quality", "jobs": ["msrv"] },
11
+ { "tool": "fuzzing", "category": "quality", "jobs": ["fuzz"] },
12
+ { "tool": "cross builds", "category": "quality", "jobs": ["cross"] },
13
+ { "tool": "toolchains", "category": "quality", "jobs": ["toolchains"] },
14
+ { "tool": "service checks", "category": "quality", "jobs": ["checks", "terraform"], "covers": "managed files, shellcheck, terraform" },
15
+ { "tool": "dependency audit", "category": "security", "jobs": ["audit"], "covers": "cargo deny, cargo vet, pip-audit, npm audit" },
16
+ { "tool": "OSV-Scanner", "category": "security", "jobs": ["osv"] },
17
+ { "tool": "dependency review", "category": "security", "jobs": ["review"] },
18
+ { "tool": "Dependabot", "category": "security", "alerts": "dependabot_alerts" },
19
+ { "tool": "code scanning", "category": "security", "alerts": "code_scanning_alerts" },
20
+ { "tool": "secret scanning", "category": "security", "alerts": "secret_scanning_alerts" },
21
+ { "tool": "Secret scanning settings", "category": "security", "settings": "secret_protection", "labels": { "secret_scanning": "Secret scanning", "secret_scanning_push_protection": "push protection" } },
22
+ { "tool": "OpenSSF Scorecard", "category": "security", "scorecard_below": 7 }
23
+ ],
24
+ "delivery": [
25
+ { "notch": "pins", "applies": "all" },
26
+ { "notch": "integration", "applies": "all" },
27
+ { "notch": "observability", "applies": "service" },
28
+ { "notch": "live-testing", "applies": "service", "hours": 24 },
29
+ { "notch": "release", "applies": "all", "days": 61 },
30
+ { "notch": "issues", "applies": "all" },
31
+ { "notch": "nightly", "applies": "all", "days": 2 },
32
+ { "notch": "protection", "applies": "all" },
33
+ { "notch": "ci", "applies": "all" }
34
+ ],
35
+ "workflows": { "ci": ["ci.yml", "main.yml"], "nightly": "nightly.yml", "deploy": "deploy.yml" },
36
+ "repositories": { "pubrules": "Sustenaut/pubrules", "pubrel": "Sustenaut/pubrel" }
37
+ }