little-sister-github 0.1.0__tar.gz

little_sister_github-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Michael Meyling
+
+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.

little_sister_github-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: little-sister-github
+Version: 0.1.0
+Summary: GitHub overview check type for little-sister.
+Keywords: monitoring,status,github,little-sister
+Author: Michael Meyling
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: little-sister>=0.3.11
+Requires-Python: >=3.11
+Project-URL: homepage, https://github.com/m-31/little-sister-github
+Project-URL: repository, https://github.com/m-31/little-sister-github
+Project-URL: issues, https://github.com/m-31/little-sister-github/issues
+Project-URL: changelog, https://github.com/m-31/little-sister-github/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# little-sister-github
+
+The **`github`** check type for [little-sister](https://github.com/m-31/little-sister):
+one node per configured team, with a child per aspect — open pull requests,
+Dependabot advisories, code-scanning and secret-scanning alerts, SBOM presence,
+workflow runs and open issues.
+
+Every finding is an individually addressable line, so an operator who opens a
+ticket for one alert can put **that line** into maintenance and the rest of the
+aspect keeps reporting.
+
+## The contract
+
+- **Requires** `little-sister >= 0.3.11` — a floor, never a pin.
+- **Runs on** Python **3.11 or newer** — the library's floor, not a higher
+  one of its own.
+- **Registers** one check type: **`github`**.
+
+## Install
+
+```toml
+# your deployment's pyproject.toml
+[project]
+dependencies = ["little-sister", "little-sister-github"]
+
+# Only while *this* one comes from git: little-sister resolves from the index.
+# Delete the table once this package is on an index too — nothing else changes.
+[tool.uv.sources]
+little-sister-github = { git = "…/little-sister-github.git", tag = "v0.1.0" }
+```
+
+```python
+# wsgi.py — registrations first, the app last. The order is load-bearing:
+# importing little_sister.app builds the engine and loads the check configs, so
+# every check type must already be registered. `isort: off` keeps an import
+# sorter from quietly reversing that.
+# isort: off
+import little_sister_github          # noqa: F401  registers the `github` type
+from little_sister.app import app
+# isort: on
+
+__all__ = ["app"]                    # without it, lint calls the app import unused
+```
+
+## Configure
+
+Copy [`examples/github.yaml`](https://github.com/m-31/little-sister-github/blob/v0.1.0/examples/github.yaml) into your deployment's
+`config/checks/`, set `org`, `team` and the token reference, and you are done —
+one file per team. The credential is a **reference**, never a value:
+
+```yaml
+type: github
+path: /platform/github
+secrets:
+  token: env://PLATFORM_GITHUB_TOKEN
+org: example-org
+team: platform
+```
+
+The token needs `read:org`, `repo`, `security_events` and dependency-graph read
+access. Each team's check carries its own credential, so a second team is a second
+config file rather than a code change.
+
+The per-aspect display text ships **with the type** and expands `{org}` / `{team}`
+from the config, so it is not copied per team. Your deployment's own policy — a
+remediation deadline, who to notify — goes in that config's `subnodes:` block,
+appended to the shipped text with `{default}`.
+
+## What it reads
+
+| Aspect | Endpoint | Grade |
+|---|---|---|
+| `pull_requests` | `GET /repos/{r}/pulls?state=open` | any open PR (minus `ignore_title_prefixes`) → **WARN** |
+| `security_advisories` | `GET /repos/{r}/dependabot/alerts?state=open` | one leaf per selected severity, graded by `security_advisories.severity_map` |
+| `code_scanning_alerts` | `GET /repos/{r}/code-scanning/alerts?state=open` | one leaf per severity, graded by `code_scanning_alerts.severity_map` |
+| `secret_scanning_alerts` | `GET /repos/{r}/secret-scanning/alerts?state=open` | any open alert → **ERROR**; scanning disabled → **ERROR** (`secret_scanning.require_enabled`) |
+| `sbom_check` | `GET /repos/{r}/dependency-graph/sbom` | no dependency graph → **ERROR** (`sbom_check.ignore`) |
+| `actions` | `GET /repos/{r}/actions/runs` | coded entries: last completed verdict, plus a newer in-flight run |
+| `issues` | `GET /repos/{r}/issues?state=open` | any open issue → **WARN** (`issues.ignore`); issues disabled → **WARN** |
+
+The check's own node carries the discovery coverage reading (`expect_min_repos`)
+and the repository roster, and rolls up worst-of its aspects. Only stdlib
+`urllib` is used — the package has no dependency but little-sister itself.
+
+## Develop
+
+little-sister is declared as a **floor** — the release that promised the surface
+this package imports — and it resolves **from the index**, like any other
+dependency. There is no `[tool.uv.sources]` table here, and the committed
+`uv.lock` is what a release runs against. To work against a local library
+checkout, add the redirect and **do not commit it**: uv reads the sources table of
+a dependency it resolves from a path or a checkout, so a committed line would
+follow this package into every deployment that installs it.
+
+```toml
+# pyproject.toml — locally, never committed
+[tool.uv.sources]
+little-sister = { path = "../little-sister" }
+```
+
+Restore `uv.lock` with it. The next `uv run` — the pre-commit gate is one — rewrites
+the lock to `source = { directory = … }`, so a redirect kept out of `pyproject.toml`
+can still reach a commit through the lock beside it.
+
+```bash
+uv sync
+uv run ruff check
+uv run mypy
+uv run mypy --python-version 3.11   # against the floor, not the interpreter you have
+uv run pytest -q
+# The same gate runs before every commit once the hook is enabled:
+git config core.hooksPath hooks
+```
+
+The tests are fixture-based; nothing in this repository calls GitHub.
+
+## License
+
+MIT — see [LICENSE](https://github.com/m-31/little-sister-github/blob/v0.1.0/LICENSE).

little_sister_github-0.1.0/README.md

@@ -0,0 +1,119 @@
+# little-sister-github
+
+The **`github`** check type for [little-sister](https://github.com/m-31/little-sister):
+one node per configured team, with a child per aspect — open pull requests,
+Dependabot advisories, code-scanning and secret-scanning alerts, SBOM presence,
+workflow runs and open issues.
+
+Every finding is an individually addressable line, so an operator who opens a
+ticket for one alert can put **that line** into maintenance and the rest of the
+aspect keeps reporting.
+
+## The contract
+
+- **Requires** `little-sister >= 0.3.11` — a floor, never a pin.
+- **Runs on** Python **3.11 or newer** — the library's floor, not a higher
+  one of its own.
+- **Registers** one check type: **`github`**.
+
+## Install
+
+```toml
+# your deployment's pyproject.toml
+[project]
+dependencies = ["little-sister", "little-sister-github"]
+
+# Only while *this* one comes from git: little-sister resolves from the index.
+# Delete the table once this package is on an index too — nothing else changes.
+[tool.uv.sources]
+little-sister-github = { git = "…/little-sister-github.git", tag = "v0.1.0" }
+```
+
+```python
+# wsgi.py — registrations first, the app last. The order is load-bearing:
+# importing little_sister.app builds the engine and loads the check configs, so
+# every check type must already be registered. `isort: off` keeps an import
+# sorter from quietly reversing that.
+# isort: off
+import little_sister_github          # noqa: F401  registers the `github` type
+from little_sister.app import app
+# isort: on
+
+__all__ = ["app"]                    # without it, lint calls the app import unused
+```
+
+## Configure
+
+Copy [`examples/github.yaml`](https://github.com/m-31/little-sister-github/blob/v0.1.0/examples/github.yaml) into your deployment's
+`config/checks/`, set `org`, `team` and the token reference, and you are done —
+one file per team. The credential is a **reference**, never a value:
+
+```yaml
+type: github
+path: /platform/github
+secrets:
+  token: env://PLATFORM_GITHUB_TOKEN
+org: example-org
+team: platform
+```
+
+The token needs `read:org`, `repo`, `security_events` and dependency-graph read
+access. Each team's check carries its own credential, so a second team is a second
+config file rather than a code change.
+
+The per-aspect display text ships **with the type** and expands `{org}` / `{team}`
+from the config, so it is not copied per team. Your deployment's own policy — a
+remediation deadline, who to notify — goes in that config's `subnodes:` block,
+appended to the shipped text with `{default}`.
+
+## What it reads
+
+| Aspect | Endpoint | Grade |
+|---|---|---|
+| `pull_requests` | `GET /repos/{r}/pulls?state=open` | any open PR (minus `ignore_title_prefixes`) → **WARN** |
+| `security_advisories` | `GET /repos/{r}/dependabot/alerts?state=open` | one leaf per selected severity, graded by `security_advisories.severity_map` |
+| `code_scanning_alerts` | `GET /repos/{r}/code-scanning/alerts?state=open` | one leaf per severity, graded by `code_scanning_alerts.severity_map` |
+| `secret_scanning_alerts` | `GET /repos/{r}/secret-scanning/alerts?state=open` | any open alert → **ERROR**; scanning disabled → **ERROR** (`secret_scanning.require_enabled`) |
+| `sbom_check` | `GET /repos/{r}/dependency-graph/sbom` | no dependency graph → **ERROR** (`sbom_check.ignore`) |
+| `actions` | `GET /repos/{r}/actions/runs` | coded entries: last completed verdict, plus a newer in-flight run |
+| `issues` | `GET /repos/{r}/issues?state=open` | any open issue → **WARN** (`issues.ignore`); issues disabled → **WARN** |
+
+The check's own node carries the discovery coverage reading (`expect_min_repos`)
+and the repository roster, and rolls up worst-of its aspects. Only stdlib
+`urllib` is used — the package has no dependency but little-sister itself.
+
+## Develop
+
+little-sister is declared as a **floor** — the release that promised the surface
+this package imports — and it resolves **from the index**, like any other
+dependency. There is no `[tool.uv.sources]` table here, and the committed
+`uv.lock` is what a release runs against. To work against a local library
+checkout, add the redirect and **do not commit it**: uv reads the sources table of
+a dependency it resolves from a path or a checkout, so a committed line would
+follow this package into every deployment that installs it.
+
+```toml
+# pyproject.toml — locally, never committed
+[tool.uv.sources]
+little-sister = { path = "../little-sister" }
+```
+
+Restore `uv.lock` with it. The next `uv run` — the pre-commit gate is one — rewrites
+the lock to `source = { directory = … }`, so a redirect kept out of `pyproject.toml`
+can still reach a commit through the lock beside it.
+
+```bash
+uv sync
+uv run ruff check
+uv run mypy
+uv run mypy --python-version 3.11   # against the floor, not the interpreter you have
+uv run pytest -q
+# The same gate runs before every commit once the hook is enabled:
+git config core.hooksPath hooks
+```
+
+The tests are fixture-based; nothing in this repository calls GitHub.
+
+## License
+
+MIT — see [LICENSE](https://github.com/m-31/little-sister-github/blob/v0.1.0/LICENSE).

little_sister_github-0.1.0/pyproject.toml

@@ -0,0 +1,125 @@
+[project]
+name = "little-sister-github"
+version = "0.1.0"
+description = "GitHub overview check type for little-sister."
+authors = [
+    { name = "Michael Meyling" }
+]
+readme = {file = "README.md", content-type = "text/markdown"}
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["monitoring", "status", "github", "little-sister"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+# The **library's floor**, not the interpreter this is developed on
+# (little-sister ADR-0054). Asking for more than the library asks would mean
+# somebody installs little-sister on 3.12 and then cannot install the package
+# that was the reason they came — and metadata is frozen per artifact, so
+# correcting it afterwards costs a version. The classifiers above repeat the
+# same claim for a human reading the index rather than a resolver, which is why
+# they start at the floor and run contiguously; the release check refuses a
+# disagreement between the two.
+requires-python = ">=3.11"
+# A **floor, and never a pin.** A deployment pins little-sister; two plugins that
+# each pinned an exact version could not be installed together at all. The floor
+# names the release that promised the check-authoring surface this module imports
+# (little-sister architecture.md §11) — a statement about that surface, not about
+# a release. The upgrade a floor cannot see, the library moving *past* the
+# surface, is caught by `require_api()` in `__init__.py`.
+#
+# **0.3.11 rather than 0.3.0**, which is where the surface was first promised:
+# 0.3.0 was tagged but never uploaded, so it names no version a resolver can
+# actually fetch, and it is 0.3.11 that lowered the library's own floor to 3.11 —
+# the floor this package promises above. A lower number would ask the index for
+# something it does not have, on an interpreter the answer could not run.
+dependencies = [
+    "little-sister>=0.3.11",
+]
+
+# The public home, and the reason it was absent until now: metadata pointing at a
+# URL that does not resolve is worse than metadata that says nothing.
+#
+# `repository` is **load-bearing, not a duplicate of `homepage`**: the release
+# refuses without it, and the published README's absolute links are built from it at
+# build time — `blob/v<version>`, so a link is immutable and cannot outlive the
+# artifact that carries it. Relocating the forge is then an edit to this one line.
+#
+# No `documentation` key: for a package this size the README *is* the documentation,
+# and it arrives with the artifact. A key pointing at a directory that holds one
+# design record would promise a manual that does not exist.
+[project.urls]
+homepage = "https://github.com/m-31/little-sister-github"
+repository = "https://github.com/m-31/little-sister-github"
+issues = "https://github.com/m-31/little-sister-github/issues"
+changelog = "https://github.com/m-31/little-sister-github/blob/main/CHANGELOG.md"
+
+# The one line that differs from a deployment's pyproject.toml: a plugin is a
+# **built** package, so a consumer can install it from a tag (and later an index).
+[tool.uv]
+package = true
+
+# **No `[tool.uv.sources]`, deliberately.** little-sister is on the index, so the
+# floor above resolves like any other dependency and there is nothing left to
+# redirect. The table is not merely unnecessary now, it is harmful: uv reads the
+# sources table of a dependency it resolves from a path or a git checkout, so a
+# committed line here would be imposed on **every deployment that installs this
+# package** (little-sister `plugin-repository.md` §3).
+#
+# To develop against a local library checkout, add the redirect and do not commit
+# it:
+#
+#     [tool.uv.sources]
+#     little-sister = { path = "../little-sister" }
+#
+# It leaves a second trace: the next `uv run` rewrites the committed `uv.lock` to
+# `source = { directory = … }`, and the pre-commit gate is a `uv run`. Restore both
+# files before committing, or the path this table exists to keep out of the package
+# arrives in the lock instead.
+
+[dependency-groups]
+# Floors match little-sister's dev group, so every repository in the family runs
+# one gate and a contributor moving between them meets one set of rules.
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.1",
+    "types-PyYAML",
+]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+# Copied from little-sister as it stands. Beyond ruff's default (E, F): import
+# sorting (I), pyupgrade (UP), bugbear (B), comprehensions (C4) and Ruff's own
+# rules (RUF). The ambiguous-unicode rules are off: reason and subnode text use
+# typographic "—", "…" and "×" on purpose.
+select = ["E", "F", "W", "I", "UP", "B", "C4", "RUF"]
+ignore = ["RUF001", "RUF002", "RUF003"]
+
+[tool.mypy]
+files = ["src"]
+strict = true
+
+[tool.pytest.ini_options]
+# Adapted, not copied: little-sister's own `addopts` names `--cov=little_sister`,
+# which from here would measure somebody else's code.
+addopts = "--cov=little_sister_github --cov-report=term-missing"
+
+[build-system]
+# One **major** line, not the `<0.12.0` uv generates: that pins the minor uv shipped
+# with and turns every uv upgrade into a release-blocking edit in every repository of
+# the family. The backend's contract here is one sentence long — a
+# `src/<import package>` layout — so a minor bump has nothing to break, and what
+# would notice one that changed the artifact anyway is not vigilance but the publish
+# step, which opens the wheel and the sdist and refuses anything the release tree
+# drops. Same bound as little-sister, verified there against both minors.
+requires = ["uv_build>=0.11.14,<1.0.0"]
+build-backend = "uv_build"

little_sister_github-0.1.0/src/little_sister_github/__init__.py

@@ -0,0 +1,24 @@
+"""little-sister check type: ``github``.
+
+Importing this package registers the type in little-sister's ``CHECK_TYPES``. A
+deployment therefore needs one line in its ``wsgi.py``, before it imports
+``little_sister.app``::
+
+    import little_sister_github          # noqa: F401  registers its type
+    from little_sister.app import app    # noqa: E402  builds the engine
+
+``require_api`` declares the **check API epoch** this package was built for. It
+refuses at startup, naming both epochs, when the library has moved past the
+surface below — the upgrade an install-time floor cannot see, because a floor has
+no ceiling (little-sister ADR-0051). Without it the same mismatch would surface as
+an ``ImportError`` from inside this package, which reads like our bug.
+"""
+from little_sister.checks import require_api
+
+require_api(1)
+
+from little_sister_github import github  # noqa: E402  registers the type
+
+__version__ = "0.1.0"
+
+__all__ = ["github"]