pubcheck 0.0.2__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.
- pubcheck/__init__.py +28 -0
- pubcheck/__main__.py +106 -0
- pubcheck/base.py +157 -0
- pubcheck/core.py +274 -0
- pubcheck/correspond.py +151 -0
- pubcheck/detectors.py +212 -0
- pubcheck/hold.py +189 -0
- pubcheck/sources.py +277 -0
- pubcheck-0.0.2.dist-info/METADATA +90 -0
- pubcheck-0.0.2.dist-info/RECORD +13 -0
- pubcheck-0.0.2.dist-info/WHEEL +4 -0
- pubcheck-0.0.2.dist-info/entry_points.txt +3 -0
- pubcheck-0.0.2.dist-info/licenses/LICENSE +21 -0
pubcheck/__init__.py
ADDED
|
@@ -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
|
+
]
|
pubcheck/__main__.py
ADDED
|
@@ -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())
|
pubcheck/base.py
ADDED
|
@@ -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)
|
pubcheck/core.py
ADDED
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
"""The check: is this text fit for the repo it is about to be published to?
|
|
2
|
+
|
|
3
|
+
:func:`check` is the one entry point every writer calls (the Claude Code hook through the
|
|
4
|
+
CLI, correspond's ``before_send``, hatchway through the CLI). It answers a :class:`Verdict`:
|
|
5
|
+
|
|
6
|
+
- ``pass``: a private target (nothing is scanned), or nothing found;
|
|
7
|
+
- ``flag``: a detector found something; the text must not be published as is;
|
|
8
|
+
- ``unavailable``: the check could not be made. For an **unattended** writer (nobody
|
|
9
|
+
reads the post before it goes out) that is a missing registry, a lookup out of time, or
|
|
10
|
+
any error; such a writer must hold the text, never post it. An attended writer proceeds
|
|
11
|
+
without the registry (the gap is logged), and only an error makes the check unavailable;
|
|
12
|
+
- ``override``: found something, but the author gave a reason to publish anyway (the
|
|
13
|
+
hook's ``# public-text-ok: <reason>``); logged with the reason.
|
|
14
|
+
|
|
15
|
+
An unknown visibility (offline, no ``gh``, no such repo, no repo named) is public.
|
|
16
|
+
|
|
17
|
+
>>> v = check("A neutral release note.", repo="o/r", public=True, log=False)
|
|
18
|
+
>>> v.decision, v.exit_code
|
|
19
|
+
('pass', 0)
|
|
20
|
+
>>> v = check("As the owner asked, we fixed it.", repo="o/r", public=True, log=False)
|
|
21
|
+
>>> v.decision, v.categories, v.exit_code
|
|
22
|
+
('flag', ['owner-relation'], 1)
|
|
23
|
+
>>> check("the owner asked", repo="o/r", public=False, log=False).decision
|
|
24
|
+
'pass'
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
from __future__ import annotations
|
|
28
|
+
|
|
29
|
+
from collections.abc import Mapping, Sequence
|
|
30
|
+
from dataclasses import dataclass, field
|
|
31
|
+
|
|
32
|
+
from pubcheck.base import MAX_TEXT, Budget, log_event, settings, text_hash
|
|
33
|
+
from pubcheck.detectors import (
|
|
34
|
+
DETECTORS,
|
|
35
|
+
UNATTENDED_DETECTORS,
|
|
36
|
+
Finding,
|
|
37
|
+
dictionary_words,
|
|
38
|
+
findings,
|
|
39
|
+
)
|
|
40
|
+
from pubcheck.sources import (
|
|
41
|
+
cached_visibility,
|
|
42
|
+
companion_exists,
|
|
43
|
+
gh_repo_view,
|
|
44
|
+
lookup_visibility,
|
|
45
|
+
origin,
|
|
46
|
+
terms_for,
|
|
47
|
+
vocabulary,
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
EXIT_CODES = {"pass": 0, "override": 0, "flag": 1, "unavailable": 2}
|
|
51
|
+
|
|
52
|
+
#: One line per category, for the author who has to reword.
|
|
53
|
+
HINTS = {
|
|
54
|
+
"registry": "names a person or org from the owner's acquaint records that a public reader may not see",
|
|
55
|
+
"owner-relation": 'relays the owner\'s own preferences, corrections or relations ("the operator stated", "my agents")',
|
|
56
|
+
"private-ref": "points at a private repo, working folder or local path",
|
|
57
|
+
"session-link": "carries a Claude session link (strip it)",
|
|
58
|
+
"credential": "carries a credential-shaped string (a token, a key, a password in a URL)",
|
|
59
|
+
"mention": "@mentions someone, which notifies them: posting it is messaging them",
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@dataclass
|
|
64
|
+
class Verdict:
|
|
65
|
+
"""What the check decided about one text, and why; :meth:`to_json` never holds the text."""
|
|
66
|
+
|
|
67
|
+
decision: str
|
|
68
|
+
repo: str = ""
|
|
69
|
+
visibility: str = "unknown" # public | private | unknown
|
|
70
|
+
findings: list[Finding] = field(default_factory=list)
|
|
71
|
+
registry: str = "skipped" # available | unavailable | skipped
|
|
72
|
+
unattended: bool = False
|
|
73
|
+
destination: str | None = None
|
|
74
|
+
reason: str | None = None
|
|
75
|
+
text_hash: str = ""
|
|
76
|
+
|
|
77
|
+
@property
|
|
78
|
+
def categories(self) -> list[str]:
|
|
79
|
+
"""The categories found, sorted, each once."""
|
|
80
|
+
return sorted({c for c, _ in self.findings})
|
|
81
|
+
|
|
82
|
+
@property
|
|
83
|
+
def exit_code(self) -> int:
|
|
84
|
+
"""0 pass (or override), 1 flag, 2 unavailable."""
|
|
85
|
+
return EXIT_CODES[self.decision]
|
|
86
|
+
|
|
87
|
+
@property
|
|
88
|
+
def held(self) -> bool:
|
|
89
|
+
"""Whether a writer must hold the text instead of publishing it."""
|
|
90
|
+
return self.decision in ("flag", "unavailable")
|
|
91
|
+
|
|
92
|
+
def to_json(self, *, terms: bool = False) -> dict:
|
|
93
|
+
"""The verdict as JSON: categories, never the text; the matched terms only on request."""
|
|
94
|
+
out = {
|
|
95
|
+
"decision": self.decision,
|
|
96
|
+
"repo": self.repo,
|
|
97
|
+
"visibility": self.visibility,
|
|
98
|
+
"categories": self.categories,
|
|
99
|
+
"registry": self.registry,
|
|
100
|
+
"unattended": self.unattended,
|
|
101
|
+
"destination": self.destination,
|
|
102
|
+
"reason": self.reason,
|
|
103
|
+
"text_hash": self.text_hash,
|
|
104
|
+
}
|
|
105
|
+
if terms:
|
|
106
|
+
out["findings"] = [list(f) for f in self.findings]
|
|
107
|
+
out["explain"] = self.explain()
|
|
108
|
+
return out
|
|
109
|
+
|
|
110
|
+
def explain(self) -> str:
|
|
111
|
+
"""For the author: what was found, by category, and where the private context goes."""
|
|
112
|
+
if self.decision == "unavailable":
|
|
113
|
+
return f"The publication check could not be made ({self.reason}), so nothing is published."
|
|
114
|
+
lines = [
|
|
115
|
+
f"{self.repo or 'an unknown (so presumed public) repo'} is public, and the text:"
|
|
116
|
+
]
|
|
117
|
+
for cat in self.categories:
|
|
118
|
+
found = ", ".join(repr(t) for c, t in self.findings if c == cat)
|
|
119
|
+
lines.append(f"- {HINTS.get(cat, cat)}: {found}")
|
|
120
|
+
lines.append(
|
|
121
|
+
"Public repos carry only what any user of the package could read. Reword it "
|
|
122
|
+
"generically (the rule, the fix, the failing case), and put the incident and the "
|
|
123
|
+
f"owner's own context in {self.destination or 'a private repo'}."
|
|
124
|
+
)
|
|
125
|
+
return "\n".join(lines)
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def destination(
|
|
129
|
+
repo: str, cache: dict, *, budget: Budget, config: Mapping | None = None
|
|
130
|
+
) -> str:
|
|
131
|
+
"""Where the private context goes: the repo's private companion, else ``private_issues``."""
|
|
132
|
+
s = settings(config)
|
|
133
|
+
name = repo.split("/")[-1] if repo else ""
|
|
134
|
+
if name and s["private_owner"]:
|
|
135
|
+
companion = f"{s['private_owner']}/_{name.lstrip('_')}"
|
|
136
|
+
if companion_exists(companion, cache, budget=budget):
|
|
137
|
+
return f"the private companion `{companion}`"
|
|
138
|
+
if s["private_issues"]:
|
|
139
|
+
return f"`{s['private_issues']}`, titled `[{repo or 'owner/repo'}] …`"
|
|
140
|
+
return "a private repo"
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def _unattended_gaps(conf: Mapping) -> list[str]:
|
|
144
|
+
"""What an unattended check needs and lacks: the operator's settings, a word list."""
|
|
145
|
+
gaps = []
|
|
146
|
+
if not conf.get("private_owner"):
|
|
147
|
+
gaps.append("no private_owner setting (the operator's config file is missing)")
|
|
148
|
+
if not dictionary_words():
|
|
149
|
+
gaps.append("no system word list (install one, e.g. the wamerican package)")
|
|
150
|
+
return gaps
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def check(
|
|
154
|
+
text: str,
|
|
155
|
+
*,
|
|
156
|
+
repo: str | None = None,
|
|
157
|
+
title: str | None = None,
|
|
158
|
+
more: Sequence[str] = (),
|
|
159
|
+
unattended: bool = False,
|
|
160
|
+
public: bool | None = None,
|
|
161
|
+
surface: str = "text",
|
|
162
|
+
override: str | None = None,
|
|
163
|
+
repo_dir: str | None = None,
|
|
164
|
+
detectors: Sequence | None = None,
|
|
165
|
+
budget: float | None = None,
|
|
166
|
+
writer: str = "pubcheck",
|
|
167
|
+
log: bool = True,
|
|
168
|
+
context: Mapping | None = None,
|
|
169
|
+
) -> Verdict:
|
|
170
|
+
"""Check ``text`` (and ``title``) for publication to ``repo``; never raises.
|
|
171
|
+
|
|
172
|
+
``more`` are other strings published with it (labels, a category, file names, the
|
|
173
|
+
people a post notifies as ``@login``). ``public`` skips the visibility lookup when the
|
|
174
|
+
caller already knows (correspond's audience). ``repo_dir`` names a checkout whose
|
|
175
|
+
``origin`` is the target when ``repo`` is not given. ``detectors`` defaults by
|
|
176
|
+
``unattended``. ``override`` is ignored when ``unattended``: nobody is there to give a
|
|
177
|
+
reason. ``context`` adds fields to the log event (a session id, a tool name), never text.
|
|
178
|
+
|
|
179
|
+
An unattended check asks GitHub for the visibility instead of trusting a cached
|
|
180
|
+
"private" (a repo made public today must not pass unscanned), and holds a text longer
|
|
181
|
+
than ``MAX_TEXT`` as unavailable.
|
|
182
|
+
"""
|
|
183
|
+
texts = [t for t in (title, text, *more) if t]
|
|
184
|
+
verdict = Verdict(
|
|
185
|
+
"pass", repo=repo or "", unattended=unattended, text_hash=text_hash(*texts)
|
|
186
|
+
)
|
|
187
|
+
conf = settings({"budget_seconds": budget})
|
|
188
|
+
b = Budget(conf["budget_seconds"])
|
|
189
|
+
|
|
190
|
+
def logged(decision_name, **extra):
|
|
191
|
+
if log:
|
|
192
|
+
log_event(
|
|
193
|
+
writer=writer,
|
|
194
|
+
surface=surface,
|
|
195
|
+
repo=verdict.repo,
|
|
196
|
+
decision=decision_name,
|
|
197
|
+
categories=verdict.categories,
|
|
198
|
+
unattended=unattended,
|
|
199
|
+
text_hash=verdict.text_hash,
|
|
200
|
+
**extra,
|
|
201
|
+
**dict(context or {}),
|
|
202
|
+
)
|
|
203
|
+
return verdict
|
|
204
|
+
|
|
205
|
+
try:
|
|
206
|
+
cache = cached_visibility()
|
|
207
|
+
remote = None
|
|
208
|
+
if not repo and repo_dir:
|
|
209
|
+
repo, remote = origin(repo_dir, budget=b)
|
|
210
|
+
verdict.repo = repo or ""
|
|
211
|
+
if public is not None:
|
|
212
|
+
private = not public
|
|
213
|
+
elif not repo:
|
|
214
|
+
private = None
|
|
215
|
+
elif unattended:
|
|
216
|
+
private = gh_repo_view(repo, budget=b) # fresh: never a cached "private"
|
|
217
|
+
private = private if isinstance(private, bool) else None
|
|
218
|
+
else:
|
|
219
|
+
private = lookup_visibility(repo, cache, budget=b, remote=remote)
|
|
220
|
+
if private is True:
|
|
221
|
+
verdict.visibility = "private"
|
|
222
|
+
return verdict
|
|
223
|
+
verdict.visibility = "public" if private is False else "unknown"
|
|
224
|
+
missing = _unattended_gaps(conf) if unattended else []
|
|
225
|
+
if missing:
|
|
226
|
+
verdict.decision = "unavailable"
|
|
227
|
+
verdict.reason = "not set up for an unattended writer: " + "; ".join(missing)
|
|
228
|
+
return logged("unavailable", reason=verdict.reason)
|
|
229
|
+
if unattended and sum(len(t) for t in texts) > MAX_TEXT:
|
|
230
|
+
verdict.decision = "unavailable"
|
|
231
|
+
verdict.reason = (
|
|
232
|
+
f"the text is longer than {MAX_TEXT} characters, which is not checked"
|
|
233
|
+
)
|
|
234
|
+
return logged("unavailable", reason=verdict.reason)
|
|
235
|
+
vocab, available = vocabulary(budget=b)
|
|
236
|
+
verdict.registry = "available" if available else "unavailable"
|
|
237
|
+
ctx = {
|
|
238
|
+
"repo": repo or "",
|
|
239
|
+
"surface": surface,
|
|
240
|
+
"terms": terms_for(vocab, repo),
|
|
241
|
+
"private_slugs": [s for s, p in cache.items() if p],
|
|
242
|
+
"private_owner": conf["private_owner"],
|
|
243
|
+
"private_patterns": conf["private_patterns"],
|
|
244
|
+
"unattended": unattended,
|
|
245
|
+
"settings": conf,
|
|
246
|
+
"budget": b,
|
|
247
|
+
}
|
|
248
|
+
if detectors is None:
|
|
249
|
+
detectors = UNATTENDED_DETECTORS if unattended else DETECTORS
|
|
250
|
+
verdict.findings = findings(texts, ctx, detectors=detectors)
|
|
251
|
+
except Exception as error: # a check that cannot judge holds the text
|
|
252
|
+
# the type only: an error's message can echo the text
|
|
253
|
+
verdict.decision, verdict.reason = (
|
|
254
|
+
"unavailable",
|
|
255
|
+
f"the check failed ({type(error).__name__})",
|
|
256
|
+
)
|
|
257
|
+
return logged("unavailable", reason=verdict.reason)
|
|
258
|
+
if not verdict.findings:
|
|
259
|
+
if not available and unattended:
|
|
260
|
+
verdict.decision = "unavailable"
|
|
261
|
+
verdict.reason = "the acquaint registry is unavailable and nobody reads this before it goes out"
|
|
262
|
+
return logged("unavailable", reason=verdict.reason)
|
|
263
|
+
if not available:
|
|
264
|
+
logged("registry-unavailable")
|
|
265
|
+
return verdict
|
|
266
|
+
if override and override.strip() and not unattended:
|
|
267
|
+
verdict.decision = "override"
|
|
268
|
+
return logged("override", reason=override.strip())
|
|
269
|
+
verdict.decision = "flag"
|
|
270
|
+
try:
|
|
271
|
+
verdict.destination = destination(repo or "", cache, budget=b)
|
|
272
|
+
except Exception:
|
|
273
|
+
verdict.destination = "a private repo"
|
|
274
|
+
return logged("block")
|