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 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,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
@@ -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