pubcheck 0.0.2__tar.gz
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.
- pubcheck-0.0.2/.github/workflows/ci.yml +43 -0
- pubcheck-0.0.2/.gitignore +10 -0
- pubcheck-0.0.2/LICENSE +21 -0
- pubcheck-0.0.2/PKG-INFO +90 -0
- pubcheck-0.0.2/README.md +60 -0
- pubcheck-0.0.2/pubcheck/__init__.py +28 -0
- pubcheck-0.0.2/pubcheck/__main__.py +106 -0
- pubcheck-0.0.2/pubcheck/base.py +157 -0
- pubcheck-0.0.2/pubcheck/core.py +274 -0
- pubcheck-0.0.2/pubcheck/correspond.py +151 -0
- pubcheck-0.0.2/pubcheck/detectors.py +212 -0
- pubcheck-0.0.2/pubcheck/hold.py +189 -0
- pubcheck-0.0.2/pubcheck/sources.py +277 -0
- pubcheck-0.0.2/pyproject.toml +131 -0
- pubcheck-0.0.2/tests/test_pubcheck.py +437 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# wads CI — calls the reusable workflow hosted in i2mint/wads.
|
|
2
|
+
#
|
|
3
|
+
# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
|
|
4
|
+
# To customize the workflow itself (rare), replace this file with the
|
|
5
|
+
# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
|
|
6
|
+
#
|
|
7
|
+
# Pinning: `@master` floats with wads. If you need version stability for
|
|
8
|
+
# a release-sensitive repo, change `@master` to a wads tag (e.g. `@0.2.15`;
|
|
9
|
+
# tags have no `v` prefix). A stub whose `secrets:` block passes the JSON
|
|
10
|
+
# transport (the default below) needs a tag from a release after 0.2.14 —
|
|
11
|
+
# older tags don't declare that secret and GitHub then rejects the
|
|
12
|
+
# workflow at parse time.
|
|
13
|
+
# CI failure does not block a published release — it blocks the publish
|
|
14
|
+
# step itself — so floating master is generally safe.
|
|
15
|
+
#
|
|
16
|
+
# Permissions: GitHub validates that the caller grants AT LEAST the
|
|
17
|
+
# permissions any job in the called workflow requests — at workflow-parse
|
|
18
|
+
# time, not at run-time, even if the job would be skipped via `if:`.
|
|
19
|
+
# The reusable workflow needs:
|
|
20
|
+
# contents: write for the publish job's version-bump push-back
|
|
21
|
+
# and for the github-pages job's gh-pages branch push
|
|
22
|
+
# pages: write for the github-pages job's REST API Pages config
|
|
23
|
+
# Both default to `write` on org-account GITHUB_TOKEN and need to be
|
|
24
|
+
# granted explicitly on personal-account callers (where the default is
|
|
25
|
+
# read-only). No `id-token: write` needed — the publish-github-pages
|
|
26
|
+
# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
|
|
27
|
+
# not the OIDC `actions/deploy-pages` flow.
|
|
28
|
+
name: Continuous Integration
|
|
29
|
+
on: [push, pull_request]
|
|
30
|
+
jobs:
|
|
31
|
+
ci:
|
|
32
|
+
uses: i2mint/wads/.github/workflows/uv-ci.yml@master
|
|
33
|
+
permissions:
|
|
34
|
+
contents: write
|
|
35
|
+
pages: write
|
|
36
|
+
# Transport (NAMED, legacy): explicitly passes only the secrets
|
|
37
|
+
# listed below (PYPI_PASSWORD + those declared in
|
|
38
|
+
# [tool.wads.ci.env]). Every name must be in the frozen wads
|
|
39
|
+
# superset (wads/ci_secrets.py) or GitHub rejects the workflow
|
|
40
|
+
# at parse time. The default JSON transport has no such limit;
|
|
41
|
+
# regenerate with `wads-migrate ci-to-stub` to switch.
|
|
42
|
+
secrets:
|
|
43
|
+
PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
|
pubcheck-0.0.2/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Thor Whalen
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
pubcheck-0.0.2/PKG-INFO
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: pubcheck
|
|
3
|
+
Version: 0.0.2
|
|
4
|
+
Summary: One publication check for every writer: is this text fit for a public repository? Personal names, the owner's own matters, private references, credentials and @mentions, failing closed when nobody is watching.
|
|
5
|
+
Project-URL: Homepage, https://github.com/thorwhalen/pubcheck
|
|
6
|
+
Project-URL: Repository, https://github.com/thorwhalen/pubcheck
|
|
7
|
+
Project-URL: Documentation, https://thorwhalen.github.io/pubcheck
|
|
8
|
+
Project-URL: Issues, https://github.com/thorwhalen/pubcheck/issues
|
|
9
|
+
Author: Thor Whalen
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: agents,claude-code,github,guard,privacy,publication
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: POSIX
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Topic :: Security
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Requires-Dist: openloops
|
|
22
|
+
Provides-Extra: correspond
|
|
23
|
+
Requires-Dist: correspond; extra == 'correspond'
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: correspond; extra == 'dev'
|
|
26
|
+
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
|
|
27
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
28
|
+
Requires-Dist: ruff>=0.1.0; extra == 'dev'
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# pubcheck
|
|
32
|
+
|
|
33
|
+
One publication check for every writer: is this text fit for the repository it is about to be published to?
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install pubcheck
|
|
37
|
+
printf '%s' "$BODY" | public-text-guard check --repo octo/app --unattended
|
|
38
|
+
# exit 0 pass, 1 flag, 2 unavailable; one JSON line naming the categories, never the text
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from pubcheck import check
|
|
43
|
+
|
|
44
|
+
v = check("As the owner asked, we fixed it.", repo="octo/app")
|
|
45
|
+
v.decision, v.categories # ('flag', ['owner-relation'])
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
A private target passes untouched. A public one, or one whose visibility is unknown, is scanned for:
|
|
49
|
+
|
|
50
|
+
- `registry`: names from the owner's acquaint records that a public reader may not see (`acquaint disclosure --audience '{"scope": "public"}'`);
|
|
51
|
+
- `owner-relation`: the owner's own preferences, corrections or relations ("the operator stated", "my agents");
|
|
52
|
+
- `private-ref`: repos known to be private, private companions, this machine's home folder, and your own `private_patterns`;
|
|
53
|
+
- `session-link`: Claude session links;
|
|
54
|
+
- `credential`: credential-shaped strings (the patterns of `openloops.egress`);
|
|
55
|
+
- `mention`: `@login` and `@org/team` outside code, for an **unattended** writer only, since a mention notifies a person.
|
|
56
|
+
|
|
57
|
+
## Attended and unattended writers
|
|
58
|
+
|
|
59
|
+
An attended writer (an agent session someone is driving) proceeds without the registry when acquaint cannot be asked, and the gap is logged. An unattended writer (a connector, a scheduled job, anything that posts with nobody reading first) fails closed: a missing registry, a lookup out of time or any error is `unavailable` (exit 2), and the text must be held, never posted.
|
|
60
|
+
|
|
61
|
+
## Three ways in, one check
|
|
62
|
+
|
|
63
|
+
- **Python**: `pubcheck.check(text, repo=..., title=..., unattended=...)` returns a `Verdict`.
|
|
64
|
+
- **CLI**: `public-text-guard check --repo OWNER/REPO [--unattended] [--title T] [--hold TARGET] [--terms]`, the text on stdin. `--terms` adds the matched terms, for a local author who has to reword; `--hold` files a held post as a desk item.
|
|
65
|
+
- **correspond**: at the top of `~/.config/correspond/config.toml`, `before_send = "pubcheck.correspond:before_send"`. Every write to a public audience is checked unattended; a held one raises correspond's `NeedsApproval` with the categories, and on a real send (not a dry run) becomes a desk item.
|
|
66
|
+
|
|
67
|
+
## Held posts become desk items
|
|
68
|
+
|
|
69
|
+
With `hold_repo` set, a held post is filed as an issue in that private repo with the label the desk reads (`hold_label`, default `escalate`): the target, the title, the text (credential-shaped strings redacted) and the categories, so it can be published as is, edited or dropped. The hold repo's visibility is asked of GitHub just before filing, and nothing is copied to a repo that is not private. The same text held twice is filed once. With no `hold_repo`, the post is still held; only the desk item is missing.
|
|
70
|
+
|
|
71
|
+
## Settings
|
|
72
|
+
|
|
73
|
+
`~/.config/pubcheck/config.toml` (`$PUBCHECK_CONFIG` names another file), then environment variables, then keyword arguments:
|
|
74
|
+
|
|
75
|
+
| key | env | default |
|
|
76
|
+
|---|---|---|
|
|
77
|
+
| `hold_repo` | `PUBCHECK_HOLD_REPO` | unset (no desk item) |
|
|
78
|
+
| `hold_label` | `PUBCHECK_HOLD_LABEL` | `escalate` |
|
|
79
|
+
| `budget_seconds` | `PUBCHECK_BUDGET_SECONDS` | `12` |
|
|
80
|
+
| `private_owner` | `PUBCHECK_PRIVATE_OWNER` | unset: the account whose `<owner>/_<name>` repos are private companions |
|
|
81
|
+
| `private_issues` | `PUBCHECK_PRIVATE_ISSUES` | unset: where context with no companion goes |
|
|
82
|
+
| `private_patterns` | (config only) | none: regexes for private references, such as working folders |
|
|
83
|
+
|
|
84
|
+
## Caches and log
|
|
85
|
+
|
|
86
|
+
Visibility comes from a cache shared with other tools (`~/.cache/priv/repo_visibility/`), then `gh repo view`. The vocabulary is cached an hour in `~/.cache/public-text-guard/`. Decisions worth keeping go to `~/.local/state/public-text-guard/events.jsonl` (mode 0600): categories, repo, writer, a short hash of the text, an error's type and an override's reason; never the text or the matched terms.
|
|
87
|
+
|
|
88
|
+
## System requirements
|
|
89
|
+
|
|
90
|
+
`gh` (authenticated) for visibility lookups and desk items; `acquaint` for the registry. Without `gh`, visibility is unknown and so public; without `acquaint`, an unattended check is unavailable.
|
pubcheck-0.0.2/README.md
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# pubcheck
|
|
2
|
+
|
|
3
|
+
One publication check for every writer: is this text fit for the repository it is about to be published to?
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pip install pubcheck
|
|
7
|
+
printf '%s' "$BODY" | public-text-guard check --repo octo/app --unattended
|
|
8
|
+
# exit 0 pass, 1 flag, 2 unavailable; one JSON line naming the categories, never the text
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```python
|
|
12
|
+
from pubcheck import check
|
|
13
|
+
|
|
14
|
+
v = check("As the owner asked, we fixed it.", repo="octo/app")
|
|
15
|
+
v.decision, v.categories # ('flag', ['owner-relation'])
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
A private target passes untouched. A public one, or one whose visibility is unknown, is scanned for:
|
|
19
|
+
|
|
20
|
+
- `registry`: names from the owner's acquaint records that a public reader may not see (`acquaint disclosure --audience '{"scope": "public"}'`);
|
|
21
|
+
- `owner-relation`: the owner's own preferences, corrections or relations ("the operator stated", "my agents");
|
|
22
|
+
- `private-ref`: repos known to be private, private companions, this machine's home folder, and your own `private_patterns`;
|
|
23
|
+
- `session-link`: Claude session links;
|
|
24
|
+
- `credential`: credential-shaped strings (the patterns of `openloops.egress`);
|
|
25
|
+
- `mention`: `@login` and `@org/team` outside code, for an **unattended** writer only, since a mention notifies a person.
|
|
26
|
+
|
|
27
|
+
## Attended and unattended writers
|
|
28
|
+
|
|
29
|
+
An attended writer (an agent session someone is driving) proceeds without the registry when acquaint cannot be asked, and the gap is logged. An unattended writer (a connector, a scheduled job, anything that posts with nobody reading first) fails closed: a missing registry, a lookup out of time or any error is `unavailable` (exit 2), and the text must be held, never posted.
|
|
30
|
+
|
|
31
|
+
## Three ways in, one check
|
|
32
|
+
|
|
33
|
+
- **Python**: `pubcheck.check(text, repo=..., title=..., unattended=...)` returns a `Verdict`.
|
|
34
|
+
- **CLI**: `public-text-guard check --repo OWNER/REPO [--unattended] [--title T] [--hold TARGET] [--terms]`, the text on stdin. `--terms` adds the matched terms, for a local author who has to reword; `--hold` files a held post as a desk item.
|
|
35
|
+
- **correspond**: at the top of `~/.config/correspond/config.toml`, `before_send = "pubcheck.correspond:before_send"`. Every write to a public audience is checked unattended; a held one raises correspond's `NeedsApproval` with the categories, and on a real send (not a dry run) becomes a desk item.
|
|
36
|
+
|
|
37
|
+
## Held posts become desk items
|
|
38
|
+
|
|
39
|
+
With `hold_repo` set, a held post is filed as an issue in that private repo with the label the desk reads (`hold_label`, default `escalate`): the target, the title, the text (credential-shaped strings redacted) and the categories, so it can be published as is, edited or dropped. The hold repo's visibility is asked of GitHub just before filing, and nothing is copied to a repo that is not private. The same text held twice is filed once. With no `hold_repo`, the post is still held; only the desk item is missing.
|
|
40
|
+
|
|
41
|
+
## Settings
|
|
42
|
+
|
|
43
|
+
`~/.config/pubcheck/config.toml` (`$PUBCHECK_CONFIG` names another file), then environment variables, then keyword arguments:
|
|
44
|
+
|
|
45
|
+
| key | env | default |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `hold_repo` | `PUBCHECK_HOLD_REPO` | unset (no desk item) |
|
|
48
|
+
| `hold_label` | `PUBCHECK_HOLD_LABEL` | `escalate` |
|
|
49
|
+
| `budget_seconds` | `PUBCHECK_BUDGET_SECONDS` | `12` |
|
|
50
|
+
| `private_owner` | `PUBCHECK_PRIVATE_OWNER` | unset: the account whose `<owner>/_<name>` repos are private companions |
|
|
51
|
+
| `private_issues` | `PUBCHECK_PRIVATE_ISSUES` | unset: where context with no companion goes |
|
|
52
|
+
| `private_patterns` | (config only) | none: regexes for private references, such as working folders |
|
|
53
|
+
|
|
54
|
+
## Caches and log
|
|
55
|
+
|
|
56
|
+
Visibility comes from a cache shared with other tools (`~/.cache/priv/repo_visibility/`), then `gh repo view`. The vocabulary is cached an hour in `~/.cache/public-text-guard/`. Decisions worth keeping go to `~/.local/state/public-text-guard/events.jsonl` (mode 0600): categories, repo, writer, a short hash of the text, an error's type and an override's reason; never the text or the matched terms.
|
|
57
|
+
|
|
58
|
+
## System requirements
|
|
59
|
+
|
|
60
|
+
`gh` (authenticated) for visibility lookups and desk items; `acquaint` for the registry. Without `gh`, visibility is unknown and so public; without `acquaint`, an unattended check is unavailable.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""pubcheck: one publication check for every writer.
|
|
2
|
+
|
|
3
|
+
Is this text fit for the repository it is about to be published to? A private target
|
|
4
|
+
passes; a public (or unknown) one is scanned for names from the owner's acquaint records,
|
|
5
|
+
the owner's own matters ("the operator stated"), private references, session links,
|
|
6
|
+
credentials, and, for an unattended writer, @mentions. An unattended writer fails closed.
|
|
7
|
+
|
|
8
|
+
>>> from pubcheck import check
|
|
9
|
+
>>> check("Fixed the parser.", repo="octo/app", public=True, log=False).decision
|
|
10
|
+
'pass'
|
|
11
|
+
|
|
12
|
+
Three ways in, one check: :func:`check` in Python, ``public-text-guard check`` on the
|
|
13
|
+
command line (exit 0 pass, 1 flag, 2 unavailable), and
|
|
14
|
+
``pubcheck.correspond:before_send`` as correspond's ``before_send``.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from pubcheck.core import Verdict, check
|
|
18
|
+
from pubcheck.detectors import DETECTORS, UNATTENDED_DETECTORS, findings
|
|
19
|
+
from pubcheck.hold import file_hold
|
|
20
|
+
|
|
21
|
+
__all__ = [
|
|
22
|
+
"DETECTORS",
|
|
23
|
+
"UNATTENDED_DETECTORS",
|
|
24
|
+
"Verdict",
|
|
25
|
+
"check",
|
|
26
|
+
"file_hold",
|
|
27
|
+
"findings",
|
|
28
|
+
]
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
"""The command line: ``public-text-guard check --repo OWNER/REPO [--unattended]``, the text on stdin.
|
|
2
|
+
|
|
3
|
+
Exit 0 pass (or override), 1 flag, 2 unavailable; one JSON object on stdout naming the
|
|
4
|
+
decision and the categories, never the text (the matched terms only with ``--terms``, for a
|
|
5
|
+
local author who has to reword). ``--unattended`` is for a writer nobody reads before the
|
|
6
|
+
post goes out: @mentions are held, and a missing registry or any failure is ``unavailable``.
|
|
7
|
+
``--hold TARGET`` (unattended) also files a held post as a desk item and adds its URL to
|
|
8
|
+
the JSON as ``desk_item``.
|
|
9
|
+
|
|
10
|
+
Usage from a script::
|
|
11
|
+
|
|
12
|
+
printf '%s' "$BODY" | public-text-guard check --repo octo/app --unattended
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import argparse
|
|
18
|
+
import json
|
|
19
|
+
import sys
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _parser() -> argparse.ArgumentParser:
|
|
23
|
+
p = argparse.ArgumentParser(
|
|
24
|
+
prog="public-text-guard", description=__doc__.splitlines()[0]
|
|
25
|
+
)
|
|
26
|
+
sub = p.add_subparsers(dest="command", required=True)
|
|
27
|
+
c = sub.add_parser("check", help="check the text on stdin for publication to --repo")
|
|
28
|
+
c.add_argument("--repo", help="OWNER/REPO the text goes to (none: presumed public)")
|
|
29
|
+
c.add_argument(
|
|
30
|
+
"--repo-dir",
|
|
31
|
+
help="a checkout whose origin is the target, when --repo is not given",
|
|
32
|
+
)
|
|
33
|
+
c.add_argument("--title", help="a title published with the text")
|
|
34
|
+
c.add_argument(
|
|
35
|
+
"--unattended",
|
|
36
|
+
action="store_true",
|
|
37
|
+
help="nobody reads it first: fail closed, hold @mentions",
|
|
38
|
+
)
|
|
39
|
+
c.add_argument(
|
|
40
|
+
"--public",
|
|
41
|
+
action="store_true",
|
|
42
|
+
help="the target is known to be public: skip the lookup",
|
|
43
|
+
)
|
|
44
|
+
c.add_argument(
|
|
45
|
+
"--surface",
|
|
46
|
+
default="cli",
|
|
47
|
+
help="what posts it (git commit, gh issue create…), for the log",
|
|
48
|
+
)
|
|
49
|
+
c.add_argument(
|
|
50
|
+
"--override", help="publish despite findings, for this reason (logged)"
|
|
51
|
+
)
|
|
52
|
+
c.add_argument(
|
|
53
|
+
"--terms", action="store_true", help="include the matched terms (local use only)"
|
|
54
|
+
)
|
|
55
|
+
c.add_argument(
|
|
56
|
+
"--hold",
|
|
57
|
+
metavar="TARGET",
|
|
58
|
+
help="on a hold, file a desk item for TARGET (e.g. github:o/r)",
|
|
59
|
+
)
|
|
60
|
+
c.add_argument("--budget", type=float, help="seconds for every lookup together")
|
|
61
|
+
c.add_argument("--session", help="a session id for the log")
|
|
62
|
+
return p
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def main(argv=None) -> int:
|
|
66
|
+
"""Run the CLI; returns the exit code (0 pass, 1 flag, 2 unavailable)."""
|
|
67
|
+
args = _parser().parse_args(argv)
|
|
68
|
+
try:
|
|
69
|
+
from pubcheck.core import check
|
|
70
|
+
|
|
71
|
+
text = sys.stdin.read()
|
|
72
|
+
verdict = check(
|
|
73
|
+
text,
|
|
74
|
+
repo=args.repo,
|
|
75
|
+
repo_dir=args.repo_dir,
|
|
76
|
+
title=args.title,
|
|
77
|
+
unattended=args.unattended,
|
|
78
|
+
public=True if args.public else None,
|
|
79
|
+
surface=args.surface,
|
|
80
|
+
override=args.override,
|
|
81
|
+
budget=args.budget,
|
|
82
|
+
writer="cli",
|
|
83
|
+
context={"session": args.session} if args.session else None,
|
|
84
|
+
)
|
|
85
|
+
out = verdict.to_json(terms=args.terms)
|
|
86
|
+
if args.hold and verdict.held:
|
|
87
|
+
from pubcheck.hold import file_hold
|
|
88
|
+
|
|
89
|
+
filed = file_hold(verdict, target=args.hold, text=text, title=args.title)
|
|
90
|
+
out["desk_item"] = filed.get("url") or f"not filed: {filed.get('reason')}"
|
|
91
|
+
print(json.dumps(out))
|
|
92
|
+
return verdict.exit_code
|
|
93
|
+
except Exception as error: # the check could not be made
|
|
94
|
+
print(
|
|
95
|
+
json.dumps(
|
|
96
|
+
{
|
|
97
|
+
"decision": "unavailable",
|
|
98
|
+
"reason": f"the check failed ({type(error).__name__})",
|
|
99
|
+
}
|
|
100
|
+
)
|
|
101
|
+
)
|
|
102
|
+
return 2
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
if __name__ == "__main__":
|
|
106
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
"""What every part of the check shares: the time budget, private files, the settings and the event log.
|
|
2
|
+
|
|
3
|
+
**The budget.** Every lookup (``gh``, ``acquaint``, ``git``) runs inside one
|
|
4
|
+
:class:`Budget`, so a check decides within its deadline instead of being killed by its
|
|
5
|
+
caller. Out of time, a lookup answers ``None`` (unknown), and the caller decides what
|
|
6
|
+
unknown means: presumed public for visibility, unavailable for the registry.
|
|
7
|
+
|
|
8
|
+
**Settings.** One mapping, read from ``~/.config/pubcheck/config.toml``
|
|
9
|
+
(``$PUBCHECK_CONFIG`` names another file), with environment variables over it, and keyword
|
|
10
|
+
arguments over both at each call site. The keys are in :data:`DFLT_SETTINGS`.
|
|
11
|
+
|
|
12
|
+
**The log.** ``~/.local/state/public-text-guard/events.jsonl`` (mode 0600,
|
|
13
|
+
``$PUBLIC_TEXT_GUARD_STATE_DIR``), one JSON object per decision worth keeping: never the
|
|
14
|
+
text and never the matched terms, only the categories, the repo, the writer, a short hash
|
|
15
|
+
of the text (so two events about the same text can be paired), an error's type, and an
|
|
16
|
+
override's reason as its author wrote it.
|
|
17
|
+
|
|
18
|
+
>>> b = Budget(0)
|
|
19
|
+
>>> b.run(["true"]) is None # no time left: no subprocess at all
|
|
20
|
+
True
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
import hashlib
|
|
26
|
+
import json
|
|
27
|
+
import os
|
|
28
|
+
import subprocess
|
|
29
|
+
import time
|
|
30
|
+
from collections.abc import Mapping
|
|
31
|
+
from pathlib import Path
|
|
32
|
+
|
|
33
|
+
import tomllib
|
|
34
|
+
|
|
35
|
+
BUDGET_SECONDS = 12.0
|
|
36
|
+
MAX_TEXT = 70_000 # characters; GitHub caps a body at 65,536, and longer is not checked
|
|
37
|
+
LOOKUP_TIMEOUT = 8.0
|
|
38
|
+
CACHE_DIR_ENV = "PUBLIC_TEXT_GUARD_CACHE_DIR"
|
|
39
|
+
CACHE_DIR = "~/.cache/public-text-guard"
|
|
40
|
+
STATE_DIR_ENV = "PUBLIC_TEXT_GUARD_STATE_DIR"
|
|
41
|
+
STATE_DIR = "~/.local/state/public-text-guard"
|
|
42
|
+
CONFIG_ENV = "PUBCHECK_CONFIG"
|
|
43
|
+
CONFIG_FILE = "~/.config/pubcheck/config.toml"
|
|
44
|
+
|
|
45
|
+
#: The settings and their defaults. Everything that names the operator's own repos or
|
|
46
|
+
#: folders is unset by default and lives in their config file, never in this code:
|
|
47
|
+
#:
|
|
48
|
+
#: - ``hold_repo``: the private repo where a held post becomes a desk item (unset: no item
|
|
49
|
+
#: is filed; it must be private, or nothing is copied there);
|
|
50
|
+
#: - ``hold_label``: the label the desk reads;
|
|
51
|
+
#: - ``private_owner``: the account whose ``<owner>/_<name>`` repos are private companions
|
|
52
|
+
#: (a reference to one is private, and a flag points at the target's companion);
|
|
53
|
+
#: - ``private_issues``: the private repo for context that has no companion;
|
|
54
|
+
#: - ``private_patterns``: more regexes for private references (working folders, the
|
|
55
|
+
#: layout of the operator's machines), on top of this machine's home folder.
|
|
56
|
+
DFLT_SETTINGS = {
|
|
57
|
+
"hold_repo": None,
|
|
58
|
+
"hold_label": "escalate",
|
|
59
|
+
"budget_seconds": BUDGET_SECONDS,
|
|
60
|
+
"private_owner": None,
|
|
61
|
+
"private_issues": None,
|
|
62
|
+
"private_patterns": (),
|
|
63
|
+
}
|
|
64
|
+
#: The environment variable that overrides each setting (``private_patterns``: config only).
|
|
65
|
+
SETTINGS_ENV = {
|
|
66
|
+
"hold_repo": "PUBCHECK_HOLD_REPO",
|
|
67
|
+
"hold_label": "PUBCHECK_HOLD_LABEL",
|
|
68
|
+
"budget_seconds": "PUBCHECK_BUDGET_SECONDS",
|
|
69
|
+
"private_owner": "PUBCHECK_PRIVATE_OWNER",
|
|
70
|
+
"private_issues": "PUBCHECK_PRIVATE_ISSUES",
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
class Budget:
|
|
75
|
+
"""One deadline shared by every lookup of a check."""
|
|
76
|
+
|
|
77
|
+
def __init__(self, seconds: float | None = BUDGET_SECONDS):
|
|
78
|
+
self.deadline = None if seconds is None else time.monotonic() + seconds
|
|
79
|
+
|
|
80
|
+
def left(self, cap: float = LOOKUP_TIMEOUT) -> float:
|
|
81
|
+
"""Seconds a lookup may take: ``cap``, or what is left of the budget when less."""
|
|
82
|
+
if self.deadline is None:
|
|
83
|
+
return cap
|
|
84
|
+
return min(cap, self.deadline - time.monotonic())
|
|
85
|
+
|
|
86
|
+
def run(self, argv, *, cap: float = LOOKUP_TIMEOUT, stdin: str | None = None):
|
|
87
|
+
"""``subprocess.run`` within the budget; ``None`` when out of time or on failure."""
|
|
88
|
+
left = self.left(cap)
|
|
89
|
+
if left <= 0.05:
|
|
90
|
+
return None
|
|
91
|
+
try:
|
|
92
|
+
return subprocess.run(
|
|
93
|
+
argv, capture_output=True, text=True, timeout=left, input=stdin
|
|
94
|
+
)
|
|
95
|
+
except (OSError, subprocess.SubprocessError):
|
|
96
|
+
return None
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def write_private(path, text: str, *, append: bool = False) -> None:
|
|
100
|
+
"""Write ``text`` to ``path`` with mode 0600, in a 0700 folder (atomically unless appending)."""
|
|
101
|
+
path = Path(path)
|
|
102
|
+
try:
|
|
103
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
104
|
+
os.chmod(path.parent, 0o700)
|
|
105
|
+
if append:
|
|
106
|
+
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
|
|
107
|
+
with os.fdopen(fd, "a") as f:
|
|
108
|
+
f.write(text)
|
|
109
|
+
return
|
|
110
|
+
tmp = path.with_name(path.name + ".tmp")
|
|
111
|
+
fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
|
|
112
|
+
with os.fdopen(fd, "w") as f:
|
|
113
|
+
f.write(text)
|
|
114
|
+
tmp.replace(path)
|
|
115
|
+
except OSError:
|
|
116
|
+
pass
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def cache_dir() -> Path:
|
|
120
|
+
"""Where the vocabulary and the companion answers are cached."""
|
|
121
|
+
return Path(os.environ.get(CACHE_DIR_ENV) or CACHE_DIR).expanduser()
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def settings(overrides: Mapping | None = None) -> dict:
|
|
125
|
+
""":data:`DFLT_SETTINGS`, then the config file, then the environment, then ``overrides``.
|
|
126
|
+
|
|
127
|
+
>>> settings({"hold_repo": "me/_desk"})["hold_repo"]
|
|
128
|
+
'me/_desk'
|
|
129
|
+
"""
|
|
130
|
+
out = dict(DFLT_SETTINGS)
|
|
131
|
+
path = Path(os.environ.get(CONFIG_ENV) or CONFIG_FILE).expanduser()
|
|
132
|
+
if path.is_file():
|
|
133
|
+
try:
|
|
134
|
+
data = tomllib.loads(path.read_text())
|
|
135
|
+
except (OSError, ValueError):
|
|
136
|
+
data = {}
|
|
137
|
+
out.update(data) # unknown keys are kept: a detector may read its own settings
|
|
138
|
+
for key, var in SETTINGS_ENV.items():
|
|
139
|
+
if os.environ.get(var):
|
|
140
|
+
out[key] = os.environ[var]
|
|
141
|
+
out.update({k: v for k, v in (overrides or {}).items() if v is not None})
|
|
142
|
+
out["budget_seconds"] = float(out["budget_seconds"])
|
|
143
|
+
out["private_patterns"] = tuple(out["private_patterns"] or ())
|
|
144
|
+
return out
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def text_hash(*texts: str) -> str:
|
|
148
|
+
"""A short hash of the texts: pairs log events and desk items without copying the text."""
|
|
149
|
+
digest = hashlib.sha256("\x00".join(t or "" for t in texts).encode()).hexdigest()
|
|
150
|
+
return digest[:16]
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def log_event(**fields) -> None:
|
|
154
|
+
"""Append one event to the private log; never raises."""
|
|
155
|
+
d = Path(os.environ.get(STATE_DIR_ENV) or STATE_DIR).expanduser()
|
|
156
|
+
record = {"v": 2, "time": time.strftime("%Y-%m-%dT%H:%M:%S%z"), **fields}
|
|
157
|
+
write_private(d / "events.jsonl", json.dumps(record) + "\n", append=True)
|