wherefore-build 0.5.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.
- wherefore/__init__.py +10 -0
- wherefore/__main__.py +5 -0
- wherefore/_observe/sitecustomize.py +294 -0
- wherefore/claims.py +134 -0
- wherefore/cli.py +227 -0
- wherefore/commands.json +57 -0
- wherefore/compare.py +285 -0
- wherefore/config.py +317 -0
- wherefore/features.json +71 -0
- wherefore/gate.py +711 -0
- wherefore/generators.py +278 -0
- wherefore/hook.py +134 -0
- wherefore/principles.json +25 -0
- wherefore/prove.py +295 -0
- wherefore/reach.py +666 -0
- wherefore/releases.json +145 -0
- wherefore/retired.py +431 -0
- wherefore/scan.py +358 -0
- wherefore/skill.py +57 -0
- wherefore/skills/wherefore/SKILL.md +159 -0
- wherefore/skills/wherefore/start.md +220 -0
- wherefore/sources.py +36 -0
- wherefore/upstream.py +278 -0
- wherefore_build-0.5.1.dist-info/METADATA +147 -0
- wherefore_build-0.5.1.dist-info/RECORD +29 -0
- wherefore_build-0.5.1.dist-info/WHEEL +5 -0
- wherefore_build-0.5.1.dist-info/entry_points.txt +2 -0
- wherefore_build-0.5.1.dist-info/licenses/LICENSE +202 -0
- wherefore_build-0.5.1.dist-info/top_level.txt +1 -0
wherefore/__init__.py
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""Wherefore: a company that compiles.
|
|
2
|
+
|
|
3
|
+
One source of truth, every asset generated from it, every change tested - so
|
|
4
|
+
nothing ships that contradicts a decision. This package is the machinery that
|
|
5
|
+
enforces it; a client's wherefore.json says what its corpus is.
|
|
6
|
+
|
|
7
|
+
Kept free of imports on purpose: the observer is loaded into every process a
|
|
8
|
+
generator starts, and nothing it does should cost a generator anything.
|
|
9
|
+
"""
|
|
10
|
+
__version__ = "0.5.1"
|
wherefore/__main__.py
ADDED
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
"""Record every path a generator opens for writing, into $WHEREFORE_WRITE_LOG.
|
|
2
|
+
|
|
3
|
+
IN WHEREFORE. This file was moved from chaotic-pendulums-co's
|
|
4
|
+
checks/_observe/sitecustomize.py with two changes and no others: the variables
|
|
5
|
+
it reads are WHEREFORE_WRITE_LOG, WHEREFORE_READ_LOG and WHEREFORE_UNIT, written
|
|
6
|
+
out literally so a guard that reads this source can find them, and the root
|
|
7
|
+
comes from WHEREFORE_ROOT. A client may keep an observer of its own - the
|
|
8
|
+
pendulum does, because its selection guard reads that file - by naming its
|
|
9
|
+
directory in wherefore.json `observer.dir` with the `env_prefix` it reads.
|
|
10
|
+
|
|
11
|
+
This is the mechanism the coverage gate is built on, and it is deliberately
|
|
12
|
+
the smallest thing that could work: Python raises an `open` audit event for
|
|
13
|
+
every file opened, whoever opens it, so one hook records them all without any
|
|
14
|
+
generator knowing it is watched.
|
|
15
|
+
|
|
16
|
+
It lives in a directory that contains NOTHING ELSE and is put on PYTHONPATH,
|
|
17
|
+
which is how Python finds a module called `sitecustomize` and imports it before
|
|
18
|
+
it runs anything. A child process inherits PYTHONPATH, so a generator that
|
|
19
|
+
shells out to another python is recorded too.
|
|
20
|
+
|
|
21
|
+
WHY NOT SCRAPE THE SOURCE. tools/audit_files.py does that - it greps the
|
|
22
|
+
generators for string literals that look like filenames - and it is the reason
|
|
23
|
+
this exists. buildpack.py writes `f"{d}cp-primary-{n}.svg"`, a name that is not
|
|
24
|
+
a literal anywhere, so the scrape misses all 53 of the marks. A list of what a
|
|
25
|
+
generator APPEARS to write drifts from what it DOES write, silently, and the
|
|
26
|
+
drift is invisible in exactly the direction that matters: a file the scrape
|
|
27
|
+
misses looks unclassified, and a file the scrape imagines looks covered.
|
|
28
|
+
|
|
29
|
+
WHY NOT mtime. Because a generator that skips its write when nothing changed
|
|
30
|
+
leaves the mtime alone, and the gate cannot tell that from a generator that was
|
|
31
|
+
never called. Both are the bug this catches. See the note in coverage_gate.py:
|
|
32
|
+
the fix was to make the generators write unconditionally, not to loosen this.
|
|
33
|
+
|
|
34
|
+
WHAT IT CANNOT SEE: a write that does not go through Python's open() - a C
|
|
35
|
+
extension calling write(2) on a descriptor it got elsewhere, or a rename over
|
|
36
|
+
a file opened under another name. Nothing in this repo does either, and the
|
|
37
|
+
gate's second half (byte-identical against a snapshot) would still catch the
|
|
38
|
+
content being wrong; only the coverage half would be fooled.
|
|
39
|
+
|
|
40
|
+
THE READ SIDE, $WHEREFORE_READ_LOG. The same event, asked the other question: not
|
|
41
|
+
"what did this make" but "what did this LOOK AT". checks/leaves_are_leaves.py
|
|
42
|
+
is built on it. A file that nothing in the heavy tier ever opens is a file a
|
|
43
|
+
change to cannot move the heavy tier's answer, and that is the only licence
|
|
44
|
+
checks/foundation.py has for letting a push skip the suite. So every open is
|
|
45
|
+
recorded, in every mode, with the script that made it:
|
|
46
|
+
|
|
47
|
+
<mode>\t<script>\t<realpath>
|
|
48
|
+
<mode>\t<unit>><script>\t<realpath> when the script is not the unit
|
|
49
|
+
|
|
50
|
+
WHOSE READ IT IS, $WHEREFORE_UNIT. One job's log holds every step's reads, and a job
|
|
51
|
+
now runs several fingerprints: the checks under `heavy`, and a long proof under
|
|
52
|
+
a fingerprint of its own, so that a push that moves neither the proof nor what
|
|
53
|
+
it proves can skip it. Holding the proof's fingerprint to the WHOLE job's log
|
|
54
|
+
would make it the job's fingerprint again and the skip worth nothing, so a read
|
|
55
|
+
has to say which of the job's units caused it - and the script that made it is
|
|
56
|
+
not that: version.py is a unit of `heavy` AND the process version_proof.py
|
|
57
|
+
starts.
|
|
58
|
+
|
|
59
|
+
So the first watched process in a tree writes its own name into WHEREFORE_UNIT, every
|
|
60
|
+
child inherits it through the environment, and every line carries it. The
|
|
61
|
+
script stays beside it, because the script is what a message has to name to be
|
|
62
|
+
worth reading. checks/leaves_are_leaves.py judges each fingerprint on the lines
|
|
63
|
+
whose UNIT is one of its tier's declared units - and on every line whose unit
|
|
64
|
+
it does not recognise, because a tree that lost the variable is a tree nobody
|
|
65
|
+
can attribute, and the safe direction is to hold every fingerprint to it.
|
|
66
|
+
|
|
67
|
+
WHEREFORE_UNIT is set by this file and never by a workflow: checks/selection_holds.py
|
|
68
|
+
reads the names this module takes from the environment and fails a step that
|
|
69
|
+
sets any of them, so a step cannot relabel another step's reads.
|
|
70
|
+
|
|
71
|
+
Only paths inside this repository, because every import of the standard
|
|
72
|
+
library is an open too, and a log of those is a log nobody reads. Imports of
|
|
73
|
+
the repo's OWN modules are kept - io.open_code raises the same event - which is
|
|
74
|
+
what makes "a generator started importing a leaf" visible as well as "a
|
|
75
|
+
generator started reading one".
|
|
76
|
+
|
|
77
|
+
copying() is the one exemption, and it is explicit rather than inferred. The
|
|
78
|
+
coverage gate snapshots every tracked file before it runs anything and puts
|
|
79
|
+
every one back afterwards; that is a byte copy for restoring, not an
|
|
80
|
+
examination, and without saying so the log would claim the gate reads the
|
|
81
|
+
whole repository - true, and useless. Anything that wraps itself in copying()
|
|
82
|
+
is saying in code "I move these bytes, I do not look at them", where a reviewer
|
|
83
|
+
can hold it to that.
|
|
84
|
+
"""
|
|
85
|
+
import contextlib
|
|
86
|
+
import os
|
|
87
|
+
import sys
|
|
88
|
+
|
|
89
|
+
_LOG = os.environ.get("WHEREFORE_WRITE_LOG")
|
|
90
|
+
_READS = os.environ.get("WHEREFORE_READ_LOG")
|
|
91
|
+
# The client's root, from the runner that put this file on PYTHONPATH. In the
|
|
92
|
+
# repository this was extracted from the observer lived three directories below
|
|
93
|
+
# the root, and that is still the fallback - but installed with the engine it
|
|
94
|
+
# lives in site-packages, where three directories up is nobody's repository, so
|
|
95
|
+
# an unset WHEREFORE_ROOT filters every read out and the leaf judge fails on an
|
|
96
|
+
# empty log: loud, and in the right direction.
|
|
97
|
+
_ROOT = os.path.realpath(os.environ.get("WHEREFORE_ROOT") or os.path.dirname(
|
|
98
|
+
os.path.dirname(os.path.dirname(os.path.realpath(__file__)))))
|
|
99
|
+
_COPYING = [0]
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
@contextlib.contextmanager
|
|
103
|
+
def copying():
|
|
104
|
+
"""Opens inside this block are byte copies, not reads. See the docstring."""
|
|
105
|
+
_COPYING[0] += 1
|
|
106
|
+
try:
|
|
107
|
+
yield
|
|
108
|
+
finally:
|
|
109
|
+
_COPYING[0] -= 1
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
if _READS:
|
|
113
|
+
_rh = open(_READS, "a", buffering=1, encoding="utf-8", errors="replace")
|
|
114
|
+
_roots = tuple({_ROOT + os.sep, os.path.abspath(_ROOT) + os.sep})
|
|
115
|
+
_who = os.path.basename(sys.argv[0]) if sys.argv and sys.argv[0] else "python"
|
|
116
|
+
|
|
117
|
+
def _unit(who):
|
|
118
|
+
"""The name of the outermost watched process in this tree.
|
|
119
|
+
|
|
120
|
+
Set once, here, and inherited by every child through the environment.
|
|
121
|
+
A process that starts before its own name is knowable ("python", while
|
|
122
|
+
site runs) does not claim the tree: it is left unset, and the log line
|
|
123
|
+
says the script alone, which the leaf check reads as unattributed and
|
|
124
|
+
holds every fingerprint to.
|
|
125
|
+
"""
|
|
126
|
+
was = os.environ.get("WHEREFORE_UNIT")
|
|
127
|
+
if was:
|
|
128
|
+
return was
|
|
129
|
+
if who and who != "python":
|
|
130
|
+
os.environ["WHEREFORE_UNIT"] = who
|
|
131
|
+
return who
|
|
132
|
+
|
|
133
|
+
def _read(event, args):
|
|
134
|
+
if event != "open" or _COPYING[0]:
|
|
135
|
+
return
|
|
136
|
+
path, mode = args[0], args[1]
|
|
137
|
+
if path is None or isinstance(path, int):
|
|
138
|
+
return
|
|
139
|
+
try:
|
|
140
|
+
p = os.fspath(path)
|
|
141
|
+
if isinstance(p, bytes):
|
|
142
|
+
p = os.fsdecode(p)
|
|
143
|
+
a = os.path.abspath(p)
|
|
144
|
+
# AN IMPORT OPENS THE CACHE, NOT THE SOURCE, once the cache is warm:
|
|
145
|
+
# brand/code/__pycache__/tokens.cpython-312.pyc, or - under a Python
|
|
146
|
+
# that sets sys.pycache_prefix, as Apple's does - the same name under
|
|
147
|
+
# ~/Library/Caches with the source's whole path inside it. Either is
|
|
148
|
+
# recorded as the .py it was compiled from, or the second import of
|
|
149
|
+
# a leaf module would be invisible, and the gate runs every
|
|
150
|
+
# generator twice. The proof found the second spelling by missing it.
|
|
151
|
+
if a.endswith(".pyc"):
|
|
152
|
+
pre = getattr(sys, "pycache_prefix", None)
|
|
153
|
+
d, name = os.path.split(a)
|
|
154
|
+
if pre and a.startswith(os.path.abspath(pre) + os.sep):
|
|
155
|
+
d = d[len(os.path.abspath(pre)):] or os.sep
|
|
156
|
+
elif os.path.basename(d) == "__pycache__":
|
|
157
|
+
d = os.path.dirname(d)
|
|
158
|
+
a = os.path.join(d, name.split(".")[0] + ".py")
|
|
159
|
+
# The cheap test first: this runs for every import of every module
|
|
160
|
+
# in every process, and almost none of them are in the repo.
|
|
161
|
+
if not a.startswith(_roots):
|
|
162
|
+
return
|
|
163
|
+
real = os.path.realpath(a)
|
|
164
|
+
if mode is None: # os.open(): the mode is in flags
|
|
165
|
+
flags = args[2] or 0
|
|
166
|
+
mode = ("w" if flags & os.O_TRUNC else "r+") \
|
|
167
|
+
if flags & (os.O_WRONLY | os.O_RDWR) else "r"
|
|
168
|
+
# sys.argv is not set yet while site runs, so the name is looked up
|
|
169
|
+
# per event rather than trusted from import time.
|
|
170
|
+
who = os.path.basename(sys.argv[0]) if getattr(sys, "argv", None) \
|
|
171
|
+
and sys.argv[0] else _who
|
|
172
|
+
unit = _unit(who)
|
|
173
|
+
_rh.write(f"{mode}\t{who if unit == who else f'{unit}>{who}'}\t{real}\n")
|
|
174
|
+
except Exception:
|
|
175
|
+
# As below: a hook that raises kills what it watches. A read that
|
|
176
|
+
# cannot be recorded is a gap, and the docstring of
|
|
177
|
+
# leaves_are_leaves.py lists the gaps it has.
|
|
178
|
+
pass
|
|
179
|
+
|
|
180
|
+
sys.addaudithook(_read)
|
|
181
|
+
|
|
182
|
+
# WHAT A BROWSER LOADS. Chromium and WebKit are not Python, so the hook
|
|
183
|
+
# above never sees the page print_layout.py prints, the hero hero_stills.py
|
|
184
|
+
# renders, or the video the walkthrough's page plays. Playwright is, and
|
|
185
|
+
# every page it drives lives in a context it made. So when Playwright's own
|
|
186
|
+
# Browser and BrowserType modules are imported, the two calls that make a
|
|
187
|
+
# context are wrapped, and each new context reports every request it sends:
|
|
188
|
+
#
|
|
189
|
+
# browser\t<script>\t<realpath> a file:// request
|
|
190
|
+
# browser-url\t<script>\t<url> anything else a page asked for
|
|
191
|
+
# playwright\t<script>\tpatched <module> | PATCH-FAILED <module>: <why>
|
|
192
|
+
#
|
|
193
|
+
# Browser.new_page makes its context through new_context, so it is covered
|
|
194
|
+
# too. A Playwright that renames these internals cannot be patched; that
|
|
195
|
+
# is written down as PATCH-FAILED, and checks/leaves_are_leaves.py fails a
|
|
196
|
+
# log that says it, rather than taking an empty request log as a clean one.
|
|
197
|
+
_PW = {"playwright._impl._browser": ("Browser", "new_context"),
|
|
198
|
+
"playwright._impl._browser_type": ("BrowserType", "launch_persistent_context")}
|
|
199
|
+
|
|
200
|
+
def _who_now():
|
|
201
|
+
who = os.path.basename(sys.argv[0]) if getattr(sys, "argv", None) \
|
|
202
|
+
and sys.argv[0] else _who
|
|
203
|
+
unit = _unit(who)
|
|
204
|
+
return who if unit == who else f"{unit}>{who}"
|
|
205
|
+
|
|
206
|
+
def _request(url):
|
|
207
|
+
try:
|
|
208
|
+
if url.startswith("file:"):
|
|
209
|
+
from urllib.parse import unquote, urlparse
|
|
210
|
+
p = os.path.realpath(unquote(urlparse(url).path))
|
|
211
|
+
_rh.write(f"browser\t{_who_now()}\t{p}\n")
|
|
212
|
+
elif not url.startswith(("data:", "about:", "blob:")):
|
|
213
|
+
_rh.write(f"browser-url\t{_who_now()}\t{url}\n")
|
|
214
|
+
except Exception:
|
|
215
|
+
pass
|
|
216
|
+
|
|
217
|
+
def _wrap(module, name):
|
|
218
|
+
cls_name, meth = _PW[name]
|
|
219
|
+
cls = getattr(module, cls_name)
|
|
220
|
+
orig = getattr(cls, meth)
|
|
221
|
+
|
|
222
|
+
async def made_a_context(self, *a, **k):
|
|
223
|
+
ctx = await orig(self, *a, **k)
|
|
224
|
+
try:
|
|
225
|
+
ctx.on("request", lambda req: _request(req.url))
|
|
226
|
+
except Exception as e:
|
|
227
|
+
_rh.write(f"playwright\t{_who_now()}\tPATCH-FAILED {name}: on('request') {e}\n")
|
|
228
|
+
return ctx
|
|
229
|
+
made_a_context.__wrapped__ = orig
|
|
230
|
+
setattr(cls, meth, made_a_context)
|
|
231
|
+
|
|
232
|
+
class _PlaywrightWatch:
|
|
233
|
+
"""A meta-path finder that finds nothing itself: it lets the real
|
|
234
|
+
finder find Playwright's two modules, and wraps their loading."""
|
|
235
|
+
|
|
236
|
+
def find_spec(self, name, path=None, target=None):
|
|
237
|
+
if name not in _PW:
|
|
238
|
+
return None
|
|
239
|
+
for finder in sys.meta_path:
|
|
240
|
+
if finder is self or not hasattr(finder, "find_spec"):
|
|
241
|
+
continue
|
|
242
|
+
spec = finder.find_spec(name, path, target)
|
|
243
|
+
if spec is not None:
|
|
244
|
+
break
|
|
245
|
+
else:
|
|
246
|
+
return None
|
|
247
|
+
loader = spec.loader
|
|
248
|
+
run = getattr(loader, "exec_module", None)
|
|
249
|
+
if run is None:
|
|
250
|
+
return spec
|
|
251
|
+
|
|
252
|
+
class Loader:
|
|
253
|
+
def create_module(self, s):
|
|
254
|
+
return loader.create_module(s)
|
|
255
|
+
|
|
256
|
+
def exec_module(self, module):
|
|
257
|
+
run(module)
|
|
258
|
+
try:
|
|
259
|
+
_wrap(module, name)
|
|
260
|
+
_rh.write(f"playwright\t{_who_now()}\tpatched {name}\n")
|
|
261
|
+
except Exception as e:
|
|
262
|
+
_rh.write(f"playwright\t{_who_now()}\tPATCH-FAILED {name}: {e}\n")
|
|
263
|
+
|
|
264
|
+
def __getattr__(self, attr):
|
|
265
|
+
return getattr(loader, attr)
|
|
266
|
+
spec.loader = Loader()
|
|
267
|
+
return spec
|
|
268
|
+
|
|
269
|
+
sys.meta_path.insert(0, _PlaywrightWatch())
|
|
270
|
+
|
|
271
|
+
if _LOG:
|
|
272
|
+
_fh = open(_LOG, "a", buffering=1, encoding="utf-8", errors="replace")
|
|
273
|
+
# The open() above is itself an open, and it happens before the hook is
|
|
274
|
+
# installed, so it cannot record itself. Anything after this point can.
|
|
275
|
+
|
|
276
|
+
def _record(event, args):
|
|
277
|
+
if event != "open":
|
|
278
|
+
return
|
|
279
|
+
path, mode = args[0], args[1]
|
|
280
|
+
# mode is None for os.open(); its flags are args[2]. A directory
|
|
281
|
+
# listing and a read both reach here too, hence the mode test.
|
|
282
|
+
if path is None or mode is None:
|
|
283
|
+
return
|
|
284
|
+
if not any(c in mode for c in "wxa+"):
|
|
285
|
+
return
|
|
286
|
+
try:
|
|
287
|
+
_fh.write(os.path.realpath(os.fspath(path)) + "\n")
|
|
288
|
+
except Exception:
|
|
289
|
+
# A hook that raises kills the generator it is watching. An
|
|
290
|
+
# unrecordable path is a gap in coverage, which the gate reports
|
|
291
|
+
# as an unclassified file - loud, and in the right place.
|
|
292
|
+
pass
|
|
293
|
+
|
|
294
|
+
sys.addaudithook(_record)
|
wherefore/claims.py
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
"""A claim may say only what someone has justified in writing.
|
|
2
|
+
|
|
3
|
+
NEW IN WHEREFORE, not moved. The repository this was extracted from enforces
|
|
4
|
+
one claim - where its product is made - with a check of its own
|
|
5
|
+
(checks/brand_integrity.py), whose grammar is about that claim and stays there.
|
|
6
|
+
What generalises is the shape of the rule: a claim has a TRIGGER ("in the USA",
|
|
7
|
+
"in Portugal", "clinically proven"), the things it may be said of, each with
|
|
8
|
+
the reason it is true, and the things it must never be said of, each with the
|
|
9
|
+
reason it is not. A sentence that triggers the claim and names anything else
|
|
10
|
+
fails, and says which word and why.
|
|
11
|
+
|
|
12
|
+
HOW A SENTENCE IS READ. Text comes from the same readers the retired-facts
|
|
13
|
+
check uses, so a claim is found wherever a person reads one - a page's text
|
|
14
|
+
nodes, a drawing's labels, a workbook's cells, a document's lines - and never in
|
|
15
|
+
code. Each trigger is matched the way a retired phrase is: whitespace- and
|
|
16
|
+
case-insensitive, bounded at both ends. What it is said OF is the run of words
|
|
17
|
+
right before it, joined by commas, "and", "or" or "&": "Assembled, tested and
|
|
18
|
+
boxed in Portugal" says assembled, tested and boxed.
|
|
19
|
+
|
|
20
|
+
A SENTENCE THAT STATES THE RULE IS NOT A CLAIM. 'It is never "made in
|
|
21
|
+
Portugal"' is the instruction, and the run right after a negation - allowing a
|
|
22
|
+
copula or a verb of saying between them - is read as stated, not claimed. A
|
|
23
|
+
negation anywhere else does not excuse it: "Made in Portugal - not negotiable"
|
|
24
|
+
makes the claim.
|
|
25
|
+
|
|
26
|
+
WHAT IT CANNOT SEE. A claim split across two sentences. A claim made with no
|
|
27
|
+
word before its trigger at all ("Portugal's finest") - add that form as its own
|
|
28
|
+
trigger. And it is strict on purpose: a word it does not know before the
|
|
29
|
+
trigger fails, because an affirmative claim nobody has justified is the one
|
|
30
|
+
this exists to stop. The fix is a line in `may_say`, with its reason.
|
|
31
|
+
"""
|
|
32
|
+
import re
|
|
33
|
+
|
|
34
|
+
from .retired import phrase_hits, readable
|
|
35
|
+
|
|
36
|
+
CONNECT = {",", "and", "&", "or", "then"}
|
|
37
|
+
NEGATION = {"never", "not", "no", "cannot", "avoid", "without"}
|
|
38
|
+
CARRIES = {"is", "are", "was", "were", "be", "been", "being", "say", "says", "said",
|
|
39
|
+
"call", "called", "write", "written", "label", "labelled", "labeled"}
|
|
40
|
+
SENTENCE = re.compile(r"(?<=[.!?])\s+|\n+")
|
|
41
|
+
TOKEN = re.compile(r"[A-Za-z][\w'-]*|[,&]")
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def trigger_rx(trigger):
|
|
45
|
+
words = [re.escape(w) for w in trigger.split()]
|
|
46
|
+
return re.compile(r"(?<![\w-])" + r"[\s\-]+".join(words) + r"(?![\w-])", re.I)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def said_of(prefix):
|
|
50
|
+
"""(the words a claim is said of, whether a negation governs them)."""
|
|
51
|
+
toks = [t.lower() for t in TOKEN.findall(prefix)]
|
|
52
|
+
if not toks or toks[-1] in CONNECT:
|
|
53
|
+
return [], False
|
|
54
|
+
run, i = [toks[-1]], len(toks) - 2
|
|
55
|
+
while i >= 0 and toks[i] in CONNECT:
|
|
56
|
+
while i >= 0 and toks[i] in CONNECT: # ", and" is one join
|
|
57
|
+
i -= 1
|
|
58
|
+
if i < 0:
|
|
59
|
+
break
|
|
60
|
+
run.append(toks[i])
|
|
61
|
+
i -= 1
|
|
62
|
+
before = toks[:i + 1]
|
|
63
|
+
while before and before[-1] in CARRIES:
|
|
64
|
+
before.pop()
|
|
65
|
+
return run[::-1], bool(before) and before[-1] in NEGATION
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def faults(claim, text):
|
|
69
|
+
"""[(the sentence, the word, why it fails)] for one chunk of readable text."""
|
|
70
|
+
rx = trigger_rx(claim["trigger"])
|
|
71
|
+
out = []
|
|
72
|
+
for sentence in SENTENCE.split(text):
|
|
73
|
+
for m in rx.finditer(sentence):
|
|
74
|
+
words, negated = said_of(sentence[:m.start()])
|
|
75
|
+
if negated:
|
|
76
|
+
continue
|
|
77
|
+
if not words:
|
|
78
|
+
out.append((sentence.strip(), "", f"says {claim['trigger']!r} of nothing "
|
|
79
|
+
f"a rule can read - name what happens there"))
|
|
80
|
+
for w in words:
|
|
81
|
+
if w in claim.get("never", {}):
|
|
82
|
+
out.append((sentence.strip(), w, claim["never"][w]))
|
|
83
|
+
elif w not in claim.get("may_say", {}):
|
|
84
|
+
out.append((sentence.strip(), w, f"nothing in may_say justifies "
|
|
85
|
+
f"{w!r} {claim['trigger']}"))
|
|
86
|
+
return out
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def main(cfg, argv=()):
|
|
90
|
+
"""`wherefore check claims`: every declared claim, against its surface."""
|
|
91
|
+
from .retired import files, tracked_files
|
|
92
|
+
claims = cfg.doc.get("claims", [])
|
|
93
|
+
if not claims:
|
|
94
|
+
print("no claims are declared - nothing here may only be said with a reason")
|
|
95
|
+
return 0
|
|
96
|
+
tracked = tracked_files(cfg.root)
|
|
97
|
+
total = 0
|
|
98
|
+
for c in claims:
|
|
99
|
+
for key in ("name", "trigger", "surface", "why"):
|
|
100
|
+
if not str(c.get(key, "")).strip():
|
|
101
|
+
print(f"::error::a claim in wherefore.json has no `{key}`")
|
|
102
|
+
return 1
|
|
103
|
+
for book in ("may_say", "never"):
|
|
104
|
+
for w, why in c.get(book, {}).items():
|
|
105
|
+
if not str(why).strip():
|
|
106
|
+
print(f"::error::{c['name']}: {book} {w!r} carries no reason. Saying a "
|
|
107
|
+
f"claim is true, or that it is not, is a statement somebody has "
|
|
108
|
+
f"to be able to stand behind")
|
|
109
|
+
return 1
|
|
110
|
+
surface = cfg.doc.get("surfaces", {}).get(c["surface"])
|
|
111
|
+
if surface is None:
|
|
112
|
+
print(f"::error::{c['name']} names the surface {c['surface']!r}, which "
|
|
113
|
+
f"wherefore.json `surfaces` does not declare")
|
|
114
|
+
return 1
|
|
115
|
+
found = []
|
|
116
|
+
for f in files(cfg.root, surface.get("include", []), surface.get("skip", []), tracked):
|
|
117
|
+
rel = str(f.relative_to(cfg.root))
|
|
118
|
+
if any(a in rel for a in surface.get("archive", [])):
|
|
119
|
+
continue
|
|
120
|
+
for chunk in readable(f):
|
|
121
|
+
if not phrase_hits(c["trigger"], [chunk]):
|
|
122
|
+
continue
|
|
123
|
+
found += [(rel, *x) for x in faults(c, chunk)]
|
|
124
|
+
print(f" {'ok ' if not found else 'FAIL'} {c['name']}: {c['trigger']!r} may be "
|
|
125
|
+
f"said of {', '.join(c.get('may_say', {})) or 'nothing'}")
|
|
126
|
+
for rel, sentence, word, why in found[:12]:
|
|
127
|
+
print(f" {rel} says {sentence[:90]!r}")
|
|
128
|
+
print(f" {word + ': ' if word else ''}{why}")
|
|
129
|
+
total += len(found)
|
|
130
|
+
if total:
|
|
131
|
+
print(f"\n::error::{total} claim(s) say something nobody has justified in writing")
|
|
132
|
+
return 1
|
|
133
|
+
print("\nevery claim says only what its rule allows")
|
|
134
|
+
return 0
|
wherefore/cli.py
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
"""wherefore - the command line.
|
|
2
|
+
|
|
3
|
+
The commands, and what each does, are said once, in commands.json beside this
|
|
4
|
+
file; `wherefore --help` prints them from there, and so does the README.
|
|
5
|
+
|
|
6
|
+
Every command finds its client by looking for wherefore.json in the working
|
|
7
|
+
directory and above it, or in WHEREFORE_ROOT.
|
|
8
|
+
|
|
9
|
+
A client that configures the engine in Python names the script that runs each
|
|
10
|
+
command in `entry`, and the command runs that script, with what was typed after
|
|
11
|
+
it, exactly as the client's own CI runs it.
|
|
12
|
+
"""
|
|
13
|
+
import os
|
|
14
|
+
import pathlib
|
|
15
|
+
import subprocess
|
|
16
|
+
import sys
|
|
17
|
+
|
|
18
|
+
from . import __version__
|
|
19
|
+
from . import config as cfgmod
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _init(args):
|
|
23
|
+
if len(args) > 1 or (args and args[0].startswith("-")):
|
|
24
|
+
if args[0] in ("-h", "--help"):
|
|
25
|
+
print("usage: wherefore init [DIR]")
|
|
26
|
+
return 0
|
|
27
|
+
print(f"::error::wherefore init takes one directory, at most: {' '.join(args)}")
|
|
28
|
+
return 2
|
|
29
|
+
target = pathlib.Path(args[0] if args else ".").resolve()
|
|
30
|
+
path = target / cfgmod.NAME
|
|
31
|
+
if path.exists():
|
|
32
|
+
print(f"::error::{path} already exists. init writes a corpus that declares "
|
|
33
|
+
f"nothing; it does not overwrite one that declares something.")
|
|
34
|
+
return 1
|
|
35
|
+
target.mkdir(parents=True, exist_ok=True)
|
|
36
|
+
import json
|
|
37
|
+
path.write_text(json.dumps(cfgmod.starter(target.name), indent=1,
|
|
38
|
+
ensure_ascii=False) + "\n", encoding="utf-8")
|
|
39
|
+
from . import skill
|
|
40
|
+
skill.write(target)
|
|
41
|
+
places = " and ".join(f"{p}/ ({agent})" for agent, p in skill.INTO.items())
|
|
42
|
+
print(f"wrote {path}\nwrote {places}: the skill a coding agent here "
|
|
43
|
+
f"reads\n\nCommit them. Then ask your agent to set up Wherefore: the skill's "
|
|
44
|
+
f"start.md is how.\nFrom the first build on, the skill is regenerated from the "
|
|
45
|
+
f"release this repository pins.\n\n`wherefore gate` names every tracked file "
|
|
46
|
+
f"nobody has accounted for, and each one is a decision:\ngenerated, authored or "
|
|
47
|
+
f"captured - with the reason written down.\n\nThen every place the product is "
|
|
48
|
+
f"described - a site, the docs, another repository - pins\nthe one that decides "
|
|
49
|
+
f"it, and fails its build on a feature it does not say: start.md, \"Every surface\".")
|
|
50
|
+
return 0
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _handed_over(cfg, command, args):
|
|
54
|
+
"""Run the client's own script for `command`, if `entry` names one; else None."""
|
|
55
|
+
argv = cfg.entry(command)
|
|
56
|
+
if argv is None:
|
|
57
|
+
return None
|
|
58
|
+
env = dict(os.environ, WHEREFORE_ROOT=str(cfg.root))
|
|
59
|
+
return subprocess.run([sys.executable, *argv, *args], cwd=cfg.root, env=env).returncode
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _configured():
|
|
63
|
+
cfg = cfgmod.load()
|
|
64
|
+
from . import gate, generators
|
|
65
|
+
gate.configure_from(cfg)
|
|
66
|
+
return cfg, generators, gate
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _takes_nothing(name, args):
|
|
70
|
+
"""An exit code for arguments a command does not take, or None.
|
|
71
|
+
|
|
72
|
+
Refused rather than ignored: a flag nobody reads is a flag somebody thinks
|
|
73
|
+
did something.
|
|
74
|
+
"""
|
|
75
|
+
if not args:
|
|
76
|
+
return None
|
|
77
|
+
rows = [c["usage"] for c in commands() if c["usage"].split()[1:2] == [name]]
|
|
78
|
+
if any(a in ("-h", "--help") for a in args):
|
|
79
|
+
print("usage: " + "\n ".join(rows))
|
|
80
|
+
return 0
|
|
81
|
+
print(f"::error::wherefore {name} takes no arguments: {' '.join(args)}")
|
|
82
|
+
return 2
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _list(args):
|
|
86
|
+
r = _handed_over(cfgmod.load(), "list", args)
|
|
87
|
+
if r is not None:
|
|
88
|
+
return r
|
|
89
|
+
r = _takes_nothing("list", args)
|
|
90
|
+
if r is not None:
|
|
91
|
+
return r
|
|
92
|
+
_cfg, G, _gate = _configured()
|
|
93
|
+
saved = sys.argv
|
|
94
|
+
try:
|
|
95
|
+
sys.argv = ["wherefore"]
|
|
96
|
+
return G.main()
|
|
97
|
+
finally:
|
|
98
|
+
sys.argv = saved
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _build(args):
|
|
102
|
+
r = _handed_over(cfgmod.load(), "build", args)
|
|
103
|
+
if r is not None:
|
|
104
|
+
return r
|
|
105
|
+
r = _takes_nothing("build", args)
|
|
106
|
+
if r is not None:
|
|
107
|
+
return r
|
|
108
|
+
_cfg, G, _gate = _configured()
|
|
109
|
+
return G.roll()
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _gate(args):
|
|
113
|
+
r = _handed_over(cfgmod.load(), "gate", args)
|
|
114
|
+
if r is not None:
|
|
115
|
+
return r
|
|
116
|
+
_cfg, _G, gate = _configured()
|
|
117
|
+
return gate.main(["wherefore", *args])
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def _prove(args):
|
|
121
|
+
cfg = cfgmod.load()
|
|
122
|
+
if args:
|
|
123
|
+
scripts = [pathlib.Path(a) for a in args]
|
|
124
|
+
else:
|
|
125
|
+
pattern = cfg.doc.get("proofs", {}).get("glob")
|
|
126
|
+
if not pattern:
|
|
127
|
+
print("::error::wherefore.json declares no `proofs` glob, and none were named")
|
|
128
|
+
return 1
|
|
129
|
+
scripts = sorted(p.relative_to(cfg.root) for p in cfg.root.glob(pattern))
|
|
130
|
+
if not scripts:
|
|
131
|
+
# "0/0 proofs held" passed, so a mistyped glob turned a CI step green.
|
|
132
|
+
print(f"::error::the `proofs` glob {pattern!r} matches no file. A proof step "
|
|
133
|
+
f"that runs nothing proves nothing")
|
|
134
|
+
return 1
|
|
135
|
+
env = dict(os.environ, WHEREFORE_ROOT=str(cfg.root))
|
|
136
|
+
# ONE AT A TIME, IN PLACE. A proof plants its fault in the working tree and
|
|
137
|
+
# puts it back; two at once in one checkout plant into each other's tree.
|
|
138
|
+
# Parallelism is one checkout per proof, which is a CI's job, not this one's.
|
|
139
|
+
failed = []
|
|
140
|
+
for s in scripts:
|
|
141
|
+
print(f"\n== {s}")
|
|
142
|
+
r = subprocess.run([sys.executable, str(s)], cwd=cfg.root, env=env)
|
|
143
|
+
if r.returncode:
|
|
144
|
+
failed.append(str(s))
|
|
145
|
+
print(f"\n{len(scripts) - len(failed)}/{len(scripts)} proofs held")
|
|
146
|
+
for f in failed:
|
|
147
|
+
print(f"::error::{f} did not hold")
|
|
148
|
+
return 1 if failed else 0
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
# The checks `wherefore check` runs, in the order commands.json lists them.
|
|
152
|
+
CHECKS = ("retired", "reach", "claims", "upstream")
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _check(args):
|
|
156
|
+
if not args:
|
|
157
|
+
print(f"::error::wherefore check NAME, where NAME is {', '.join(CHECKS)}")
|
|
158
|
+
return 1
|
|
159
|
+
name, rest = args[0], args[1:]
|
|
160
|
+
cfg = cfgmod.load()
|
|
161
|
+
r = _handed_over(cfg, f"check {name}", rest)
|
|
162
|
+
if r is not None:
|
|
163
|
+
return r
|
|
164
|
+
if name == "retired":
|
|
165
|
+
from . import retired
|
|
166
|
+
return retired.main(cfg, rest)
|
|
167
|
+
if name == "reach":
|
|
168
|
+
from . import reach
|
|
169
|
+
reach.configure_from(cfg)
|
|
170
|
+
return reach.main(["wherefore", *rest]) or 0
|
|
171
|
+
if name == "claims":
|
|
172
|
+
from . import claims
|
|
173
|
+
return claims.main(cfg, rest)
|
|
174
|
+
if name == "upstream":
|
|
175
|
+
from . import upstream
|
|
176
|
+
return upstream.main(cfg, rest)
|
|
177
|
+
print(f"::error::no check called {name!r}: {', '.join(CHECKS)}")
|
|
178
|
+
return 1
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def _hook(args):
|
|
182
|
+
from . import hook
|
|
183
|
+
return hook.main(cfgmod.load(), args)
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def _scan(args):
|
|
187
|
+
# NO wherefore.json: the scan is the first win, before there is a corpus.
|
|
188
|
+
from . import scan
|
|
189
|
+
return scan.main(args)
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
COMMANDS = {"init": _init, "list": _list, "build": _build, "gate": _gate,
|
|
193
|
+
"prove": _prove, "check": _check, "hook": _hook, "scan": _scan}
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def commands():
|
|
197
|
+
"""The commands as commands.json says them: [{usage, does}]."""
|
|
198
|
+
import json
|
|
199
|
+
path = pathlib.Path(__file__).resolve().parent / "commands.json"
|
|
200
|
+
return json.loads(path.read_text(encoding="utf-8"))["commands"]
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def usage():
|
|
204
|
+
rows = commands()
|
|
205
|
+
width = max(len(c["usage"]) for c in rows) + 2
|
|
206
|
+
listing = "\n".join(f" {c['usage']:<{width}}{c['does']}" for c in rows)
|
|
207
|
+
return __doc__.replace("\n\nThe commands, and what each does,",
|
|
208
|
+
"\n\n" + listing + "\n\nThe commands, and what each does,", 1)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def main(argv=None):
|
|
212
|
+
argv = list(sys.argv[1:] if argv is None else argv)
|
|
213
|
+
if not argv or argv[0] in ("-h", "--help", "help"):
|
|
214
|
+
print(usage())
|
|
215
|
+
return 0
|
|
216
|
+
if argv[0] == "--version":
|
|
217
|
+
print(f"wherefore {__version__}")
|
|
218
|
+
return 0
|
|
219
|
+
cmd = COMMANDS.get(argv[0])
|
|
220
|
+
if cmd is None:
|
|
221
|
+
print(f"::error::no command {argv[0]!r}. `wherefore --help` lists them.")
|
|
222
|
+
return 2
|
|
223
|
+
try:
|
|
224
|
+
return cmd(argv[1:])
|
|
225
|
+
except cfgmod.ConfigError as e:
|
|
226
|
+
print(e.code)
|
|
227
|
+
return 1
|