edify-agents-cli 0.2.0__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.
- edify/__init__.py +19 -0
- edify/__main__.py +6 -0
- edify/_toml.py +286 -0
- edify/agents.py +261 -0
- edify/anim.py +499 -0
- edify/assets/commands/build.md +64 -0
- edify/assets/commands/plan.md +68 -0
- edify/assets/commands/spec.md +63 -0
- edify/assets/commands/tasks.md +65 -0
- edify/assets/commands/verify.md +67 -0
- edify/assets/formats/plan.example.md +455 -0
- edify/assets/formats/plan.format.md +128 -0
- edify/assets/formats/spec.example.md +483 -0
- edify/assets/formats/spec.format.md +116 -0
- edify/assets/formats/tasks.example.md +712 -0
- edify/assets/formats/tasks.format.md +199 -0
- edify/assets/harvest/harvest.md +91 -0
- edify/assets/harvest/sources.md +295 -0
- edify/assets/harvest/vocab.md +52 -0
- edify/assets/manifest.md +30 -0
- edify/assets/mcp/default-registry.md +66 -0
- edify/assets/skills/adversary.md +61 -0
- edify/assets/skills/debugger.md +64 -0
- edify/assets/skills/implementer-general.md +53 -0
- edify/assets/skills/implementer-go.md +63 -0
- edify/assets/skills/implementer-node.md +61 -0
- edify/assets/skills/implementer-postgres.md +63 -0
- edify/assets/skills/implementer-python.md +65 -0
- edify/assets/skills/implementer-react.md +65 -0
- edify/assets/skills/planner.md +58 -0
- edify/assets/skills/test-writer-node.md +64 -0
- edify/assets/skills/test-writer-python.md +60 -0
- edify/assets/skills/verifier.md +67 -0
- edify/assets/templates/CLAUDE.md +18 -0
- edify/assets.py +77 -0
- edify/cli.py +681 -0
- edify/commands/__init__.py +1 -0
- edify/commands/check_cmd.py +72 -0
- edify/commands/doctor_cmd.py +206 -0
- edify/commands/feedback_cmd.py +90 -0
- edify/commands/governance_cmd.py +65 -0
- edify/commands/graph_cmd.py +156 -0
- edify/commands/harvest_cmd.py +538 -0
- edify/commands/init_cmd.py +333 -0
- edify/commands/init_new_cmd.py +151 -0
- edify/commands/license_cmd.py +80 -0
- edify/commands/mcp_cmd.py +159 -0
- edify/commands/self_cmd.py +185 -0
- edify/commands/setup_cmd.py +79 -0
- edify/commands/skills_cmd.py +177 -0
- edify/commands/upgrade_cmd.py +178 -0
- edify/context.py +57 -0
- edify/conventions.py +275 -0
- edify/detect.py +313 -0
- edify/distribution.py +40 -0
- edify/errors.py +66 -0
- edify/feedback.py +207 -0
- edify/formats/__init__.py +11 -0
- edify/formats/check.py +573 -0
- edify/formats/document.py +238 -0
- edify/formats/finding.py +50 -0
- edify/formats/fix.py +114 -0
- edify/formats/mcp.py +126 -0
- edify/formats/plan.py +151 -0
- edify/formats/skill.py +139 -0
- edify/formats/spec.py +164 -0
- edify/formats/tasks.py +321 -0
- edify/governance.py +316 -0
- edify/graph/__init__.py +11 -0
- edify/graph/extract.py +351 -0
- edify/graph/ignore.py +107 -0
- edify/graph/langs/__init__.py +93 -0
- edify/graph/langs/ctags.py +145 -0
- edify/graph/langs/markdown.py +41 -0
- edify/graph/langs/patterns.py +361 -0
- edify/graph/langs/python_ast.py +154 -0
- edify/graph/langs/sqlish.py +86 -0
- edify/graph/model.py +102 -0
- edify/graph/queries.py +211 -0
- edify/graph/store.py +157 -0
- edify/harvest/__init__.py +28 -0
- edify/harvest/ledger.py +191 -0
- edify/harvest/screen.py +236 -0
- edify/harvest/sources.py +298 -0
- edify/host.py +345 -0
- edify/interview.py +354 -0
- edify/library.py +176 -0
- edify/licensing/__init__.py +30 -0
- edify/licensing/ed25519.py +154 -0
- edify/licensing/projects.py +223 -0
- edify/licensing/tier.py +172 -0
- edify/licensing/token.py +149 -0
- edify/paths.py +282 -0
- edify/selfinstall.py +244 -0
- edify/skills.py +108 -0
- edify/tsv.py +109 -0
- edify/ui.py +334 -0
- edify_agents_cli-0.2.0.dist-info/METADATA +408 -0
- edify_agents_cli-0.2.0.dist-info/RECORD +102 -0
- edify_agents_cli-0.2.0.dist-info/WHEEL +4 -0
- edify_agents_cli-0.2.0.dist-info/entry_points.txt +2 -0
- edify_agents_cli-0.2.0.dist-info/licenses/LICENSE +21 -0
edify/harvest/screen.py
ADDED
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
"""Step ② — mechanical, fail-closed, no judgment.
|
|
2
|
+
|
|
3
|
+
Three checks, and none of them is a reading. A model is good at deciding whether a
|
|
4
|
+
skill file is *worth* having and bad at deciding whether we are *allowed* to have
|
|
5
|
+
it, so the second question is answered by a lookup table here and never by a prompt.
|
|
6
|
+
|
|
7
|
+
Precedence when several checks fail: an injection hit always wins and sends the
|
|
8
|
+
candidate to **quarantine**, because a flagged file preserved on disk is worth more
|
|
9
|
+
than a rejected one thrown away — someone will want to know what was attempted. A
|
|
10
|
+
licence or duplicate failure with a clean scan is a plain **reject**.
|
|
11
|
+
|
|
12
|
+
Every check is negative-by-default. An unrecognised licence string is not "probably
|
|
13
|
+
fine"; it is `NONE-FOUND`, and `NONE-FOUND` is rejected.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import re
|
|
19
|
+
import unicodedata
|
|
20
|
+
from dataclasses import dataclass, field
|
|
21
|
+
from pathlib import Path
|
|
22
|
+
|
|
23
|
+
# Permissive only, as SPDX ids. Copyleft is absent deliberately rather than by
|
|
24
|
+
# oversight: this library composes into other companies' repositories, and a
|
|
25
|
+
# reciprocal obligation travelling into a customer's tree is not ours to accept.
|
|
26
|
+
ALLOWED_LICENSES = (
|
|
27
|
+
"MIT",
|
|
28
|
+
"Apache-2.0",
|
|
29
|
+
"BSD-2-Clause",
|
|
30
|
+
"BSD-3-Clause",
|
|
31
|
+
"ISC",
|
|
32
|
+
"Unlicense",
|
|
33
|
+
"CC0-1.0",
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
# What people actually write in a LICENSE header, mapped to the id it means. An
|
|
37
|
+
# input that is not in this table and not already an allowed id stays unresolved.
|
|
38
|
+
_LICENSE_ALIASES = {
|
|
39
|
+
"mit": "MIT",
|
|
40
|
+
"mit license": "MIT",
|
|
41
|
+
"expat": "MIT",
|
|
42
|
+
"apache 2": "Apache-2.0",
|
|
43
|
+
"apache 2.0": "Apache-2.0",
|
|
44
|
+
"apache-2": "Apache-2.0",
|
|
45
|
+
"apache license 2.0": "Apache-2.0",
|
|
46
|
+
"asl-2.0": "Apache-2.0",
|
|
47
|
+
"bsd": "", # ambiguous between 2- and 3-clause, so it resolves to nothing
|
|
48
|
+
"bsd-2": "BSD-2-Clause",
|
|
49
|
+
"bsd 2-clause": "BSD-2-Clause",
|
|
50
|
+
"simplified bsd": "BSD-2-Clause",
|
|
51
|
+
"bsd-3": "BSD-3-Clause",
|
|
52
|
+
"bsd 3-clause": "BSD-3-Clause",
|
|
53
|
+
"new bsd": "BSD-3-Clause",
|
|
54
|
+
"isc": "ISC",
|
|
55
|
+
"unlicense": "Unlicense",
|
|
56
|
+
"the unlicense": "Unlicense",
|
|
57
|
+
"cc0": "CC0-1.0",
|
|
58
|
+
"cc0 1.0": "CC0-1.0",
|
|
59
|
+
"public domain": "", # a claim, not a licence
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
# Instruction-like content aimed at the three things a skill file could do to the
|
|
63
|
+
# session that loads it. Each pattern is deliberately narrow: this scan routes to a
|
|
64
|
+
# human, so a false positive costs a minute and a false negative costs a customer.
|
|
65
|
+
INJECTION_PATTERNS: tuple[tuple[str, str, str], ...] = (
|
|
66
|
+
# -- gate evasion: talking past the instructions that are already loaded
|
|
67
|
+
("override-instructions", r"ignore\s+(all\s+)?(the\s+)?(previous|prior|above|earlier)\s+instructions",
|
|
68
|
+
"tells the session to discard its instructions"),
|
|
69
|
+
("override-system", r"(disregard|override|forget)\s+(the\s+)?(system\s+prompt|your\s+(system\s+)?instructions|all\s+rules)",
|
|
70
|
+
"tells the session to discard its system prompt"),
|
|
71
|
+
("persona-reset", r"\byou\s+are\s+now\s+(a|an|in)\b|\bdeveloper\s+mode\b|\bjailbreak\b",
|
|
72
|
+
"attempts a persona or mode reset"),
|
|
73
|
+
("conceal", r"(do\s+not|don't|never)\s+(tell|inform|mention\s+to|show)\s+(the\s+)?(user|human|operator)",
|
|
74
|
+
"asks the session to keep something from the person running it"),
|
|
75
|
+
("silent-action", r"\b(silently|without\s+(asking|confirmation|informing|telling))\s+(run|execute|delete|push|commit|send|install)",
|
|
76
|
+
"asks for an unannounced action"),
|
|
77
|
+
# -- gate evasion: the checks EDIFY exists to keep
|
|
78
|
+
("skip-verification", r"(skip|bypass|disable|avoid)\s+(the\s+)?(tests?|test\s+suite|review|verification|linting|type\s?check|ci)",
|
|
79
|
+
"asks for a check to be skipped"),
|
|
80
|
+
("no-verify", r"--no-verify|--no-gpg-sign|--force-with-lease\s+.*--no-verify",
|
|
81
|
+
"asks for a git hook or signature to be bypassed"),
|
|
82
|
+
("auto-approve", r"(always|automatically)\s+(approve|accept|say\s+yes|confirm)",
|
|
83
|
+
"asks for blanket approval"),
|
|
84
|
+
# -- exfiltration
|
|
85
|
+
("secret-read", r"(\.env\b|\.aws/credentials|\.ssh/id_[a-z0-9]+|~/\.netrc|id_rsa)",
|
|
86
|
+
"names a credential file"),
|
|
87
|
+
("secret-egress", r"(curl|wget|Invoke-WebRequest|fetch\()[^\n]{0,120}(\$\{?[A-Z_]{2,}(KEY|TOKEN|SECRET|PASSWORD)|process\.env|os\.environ)",
|
|
88
|
+
"sends environment values to a network endpoint"),
|
|
89
|
+
("env-egress", r"(process\.env|os\.environ)[^\n]{0,120}(curl|wget|https?://|requests\.(post|get)|fetch\()",
|
|
90
|
+
"reads the environment next to a network call"),
|
|
91
|
+
("encoded-exec", r"(base64\s+(-d|--decode)|atob\()[^\n]{0,60}\|\s*(sh|bash|zsh|python)",
|
|
92
|
+
"decodes and executes in one step"),
|
|
93
|
+
# -- tool abuse
|
|
94
|
+
("destructive", r"rm\s+-rf\s+[~/]|git\s+push\s+(--force|-f)\b|git\s+reset\s+--hard\s+origin|DROP\s+(TABLE|DATABASE)",
|
|
95
|
+
"names a destructive command"),
|
|
96
|
+
("permission-widening", r"chmod\s+777|sudo\s+(su|-i)\b|Set-ExecutionPolicy\s+Bypass",
|
|
97
|
+
"widens permissions"),
|
|
98
|
+
)
|
|
99
|
+
|
|
100
|
+
_COMPILED = tuple((code, re.compile(pat, re.IGNORECASE), why) for code, pat, why in INJECTION_PATTERNS)
|
|
101
|
+
|
|
102
|
+
# Zero-width and bidirectional control characters. Legitimate prose in a skill file
|
|
103
|
+
# has no use for them, and text that renders as one thing and parses as another is
|
|
104
|
+
# the whole trick.
|
|
105
|
+
_HIDDEN = {
|
|
106
|
+
"": "zero-width space",
|
|
107
|
+
"": "zero-width non-joiner",
|
|
108
|
+
"": "zero-width joiner",
|
|
109
|
+
"": "word joiner",
|
|
110
|
+
"": "zero-width no-break space",
|
|
111
|
+
"": "bidi override",
|
|
112
|
+
"": "bidi override",
|
|
113
|
+
"": "bidi override",
|
|
114
|
+
"": "bidi override",
|
|
115
|
+
"": "bidi isolate",
|
|
116
|
+
"": "bidi isolate",
|
|
117
|
+
"": "bidi isolate",
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
@dataclass
|
|
122
|
+
class Check:
|
|
123
|
+
code: str
|
|
124
|
+
ok: bool
|
|
125
|
+
detail: str
|
|
126
|
+
line: int = 0
|
|
127
|
+
|
|
128
|
+
def to_json(self) -> dict:
|
|
129
|
+
return {"code": self.code, "ok": self.ok, "detail": self.detail, "line": self.line}
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
@dataclass
|
|
133
|
+
class Verdict:
|
|
134
|
+
verdict: str # pass | reject | quarantine
|
|
135
|
+
checks: list[Check] = field(default_factory=list)
|
|
136
|
+
|
|
137
|
+
@property
|
|
138
|
+
def failures(self) -> list[Check]:
|
|
139
|
+
return [c for c in self.checks if not c.ok]
|
|
140
|
+
|
|
141
|
+
def to_json(self) -> dict:
|
|
142
|
+
return {"verdict": self.verdict, "checks": [c.to_json() for c in self.checks]}
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
# -- the three checks -------------------------------------------------------
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def resolve_license(found: str) -> str:
|
|
149
|
+
"""An SPDX id from whatever the repository actually said, or `NONE-FOUND`.
|
|
150
|
+
|
|
151
|
+
Unresolvable is the same answer as absent. "BSD" and "public domain" both land
|
|
152
|
+
here, and both are the caller's problem to pin down rather than ours to guess.
|
|
153
|
+
"""
|
|
154
|
+
text = (found or "").strip()
|
|
155
|
+
if not text or text.upper() in ("NONE-FOUND", "NONE", "-", "UNKNOWN"):
|
|
156
|
+
return "NONE-FOUND"
|
|
157
|
+
for spdx in ALLOWED_LICENSES:
|
|
158
|
+
if text.lower() == spdx.lower():
|
|
159
|
+
return spdx
|
|
160
|
+
return _LICENSE_ALIASES.get(text.lower(), "") or "NONE-FOUND"
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def check_license(found: str) -> Check:
|
|
164
|
+
spdx = resolve_license(found)
|
|
165
|
+
if spdx in ALLOWED_LICENSES:
|
|
166
|
+
return Check("license", True, f"{spdx} is on the allowlist")
|
|
167
|
+
return Check(
|
|
168
|
+
"license",
|
|
169
|
+
False,
|
|
170
|
+
f"`{found or 'NONE-FOUND'}` resolves to {spdx} — the allowlist is {', '.join(ALLOWED_LICENSES)}",
|
|
171
|
+
)
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def check_duplicate(name: str, content_sha: str, library_dirs: list[Path], existing_shas: dict[str, str]) -> Check:
|
|
175
|
+
"""Against the installed library by name, and against everything ever seen by hash."""
|
|
176
|
+
for directory in library_dirs:
|
|
177
|
+
if not directory.is_dir():
|
|
178
|
+
continue
|
|
179
|
+
if (directory / f"{name}.md").is_file():
|
|
180
|
+
return Check("duplicate", False, f"{name} already exists at {(directory / f'{name}.md').as_posix()}")
|
|
181
|
+
if content_sha in existing_shas:
|
|
182
|
+
return Check("duplicate", False, f"identical bytes already handled as {existing_shas[content_sha]}")
|
|
183
|
+
return Check("duplicate", True, "no entry with this name or these bytes")
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def scan_injection(content: str) -> list[Check]:
|
|
187
|
+
"""Every hit, with its line. Never the first hit only — the report is the point."""
|
|
188
|
+
hits: list[Check] = []
|
|
189
|
+
lines = content.splitlines()
|
|
190
|
+
|
|
191
|
+
for code, pattern, why in _COMPILED:
|
|
192
|
+
for number, line in enumerate(lines, start=1):
|
|
193
|
+
if pattern.search(line):
|
|
194
|
+
hits.append(Check(code, False, f"{why}: {line.strip()[:120]}", number))
|
|
195
|
+
break # one hit per pattern is enough to route this to a human
|
|
196
|
+
|
|
197
|
+
for number, line in enumerate(lines, start=1):
|
|
198
|
+
for ch, label in _HIDDEN.items():
|
|
199
|
+
if ch in line:
|
|
200
|
+
hits.append(Check("hidden-characters", False, f"{label} (U+{ord(ch):04X}) in the text", number))
|
|
201
|
+
break
|
|
202
|
+
|
|
203
|
+
for number, line in enumerate(lines, start=1):
|
|
204
|
+
if any(unicodedata.category(ch) == "Cf" and ch not in _HIDDEN for ch in line):
|
|
205
|
+
hits.append(Check("format-characters", False, "unicode format characters in the text", number))
|
|
206
|
+
break
|
|
207
|
+
|
|
208
|
+
return hits
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def screen(
|
|
212
|
+
*,
|
|
213
|
+
name: str,
|
|
214
|
+
license_found: str,
|
|
215
|
+
content: str,
|
|
216
|
+
content_sha: str,
|
|
217
|
+
library_dirs: list[Path],
|
|
218
|
+
existing_shas: dict[str, str],
|
|
219
|
+
) -> Verdict:
|
|
220
|
+
"""All three checks, all reported, one verdict.
|
|
221
|
+
|
|
222
|
+
Nothing short-circuits. A candidate that fails the licence check is still
|
|
223
|
+
scanned, because "what did this file try to do" is a question worth an answer
|
|
224
|
+
even when the file is going in the bin either way.
|
|
225
|
+
"""
|
|
226
|
+
checks = [check_license(license_found), check_duplicate(name, content_sha, library_dirs, existing_shas)]
|
|
227
|
+
injection = scan_injection(content)
|
|
228
|
+
checks.extend(injection)
|
|
229
|
+
if not injection:
|
|
230
|
+
checks.append(Check("injection", True, "no instruction-like content found"))
|
|
231
|
+
|
|
232
|
+
if injection:
|
|
233
|
+
return Verdict("quarantine", checks)
|
|
234
|
+
if any(not c.ok for c in checks):
|
|
235
|
+
return Verdict("reject", checks)
|
|
236
|
+
return Verdict("pass", checks)
|
edify/harvest/sources.py
ADDED
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
"""`edify/harvest/sources.md` — the source table, and which row a run draws from.
|
|
2
|
+
|
|
3
|
+
Two jobs, both mechanical.
|
|
4
|
+
|
|
5
|
+
**The parse.** A markdown table because a person reviews additions to it. Read by
|
|
6
|
+
column *name* rather than position, so the table can gain a column — it gained
|
|
7
|
+
`fetch` — without every older table becoming unparseable.
|
|
8
|
+
|
|
9
|
+
**The choice.** A run has a budget of a few candidates and a list of places to draw
|
|
10
|
+
them from, and picking the place was the step nobody specified: the skill said "read
|
|
11
|
+
sources.md" and left the selection to whatever the model felt like that morning.
|
|
12
|
+
That is a lookup, so it is done here and never by a prompt — same law as the licence
|
|
13
|
+
allowlist. `rank` scores every row from the ledger's own yield history and returns
|
|
14
|
+
them ordered, with the arithmetic attached so the answer can be argued with.
|
|
15
|
+
|
|
16
|
+
What the score is made of, and why each part is in it:
|
|
17
|
+
|
|
18
|
+
eligible a posture that resolves to an allowlisted SPDX id can be
|
|
19
|
+
staged; an index can only be read for links; anything else
|
|
20
|
+
cannot be harvested at all and ranks last with the reason
|
|
21
|
+
yield admitted / (admitted + rejected), from the human door and
|
|
22
|
+
never from the screen — a source with a high screen pass rate
|
|
23
|
+
and a low admission rate is producing plausible files, which
|
|
24
|
+
is the failure mode worth ranking down
|
|
25
|
+
untried an unknown yield beats a known-bad one and loses to a
|
|
26
|
+
known-good one, which is the whole of what "unknown" means
|
|
27
|
+
archived an upstream that is frozen has a fixed amount left in it and
|
|
28
|
+
nothing new arriving, so it ranks below every live source with
|
|
29
|
+
the same posture — this is what the first version got wrong,
|
|
30
|
+
because with no such term four MIT rows tied on score and the
|
|
31
|
+
alphabetical tie-break handed the run an archived repository
|
|
32
|
+
exhaustion every candidate already in the ledger from this source is one
|
|
33
|
+
fewer left in it; a source drawn from eight times is tapped
|
|
34
|
+
out relative to a fresh one
|
|
35
|
+
staleness a month since the last run brings a good source back around
|
|
36
|
+
|
|
37
|
+
Ties break on the source name, so the answer is the same on Tuesday.
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
from __future__ import annotations
|
|
41
|
+
|
|
42
|
+
import re
|
|
43
|
+
from dataclasses import dataclass, field
|
|
44
|
+
from datetime import date
|
|
45
|
+
from pathlib import Path
|
|
46
|
+
|
|
47
|
+
from . import screen as screener
|
|
48
|
+
|
|
49
|
+
# What a row's `kind` can say about how it is drawn from. Anything else is treated
|
|
50
|
+
# as `repository` — the table is authored by a person and a typo should not silently
|
|
51
|
+
# change what a run does with the row.
|
|
52
|
+
KINDS = ("repository", "index", "engagement")
|
|
53
|
+
|
|
54
|
+
# Columns may be missing from an older table (`fetch`, `status`), and the yield
|
|
55
|
+
# columns are advisory — the ledger is the thing that actually knows.
|
|
56
|
+
_HEADERS = {
|
|
57
|
+
"source": ("source",),
|
|
58
|
+
"kind": ("kind",),
|
|
59
|
+
"fetch": ("fetch", "where", "path"),
|
|
60
|
+
"posture": ("licence posture", "license posture", "licence", "license", "posture"),
|
|
61
|
+
"status": ("status", "state"),
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
# A frozen upstream. Absent from the table means live, because most rows are.
|
|
65
|
+
ARCHIVED = ("archived", "frozen", "deprecated", "unmaintained")
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@dataclass
|
|
69
|
+
class Source:
|
|
70
|
+
name: str
|
|
71
|
+
kind: str = "repository"
|
|
72
|
+
fetch: str = ""
|
|
73
|
+
posture: str = ""
|
|
74
|
+
status: str = "active"
|
|
75
|
+
|
|
76
|
+
@property
|
|
77
|
+
def archived(self) -> bool:
|
|
78
|
+
return self.status.strip().lower() in ARCHIVED
|
|
79
|
+
|
|
80
|
+
@property
|
|
81
|
+
def spdx(self) -> str:
|
|
82
|
+
"""The posture resolved to an SPDX id, or `NONE-FOUND`.
|
|
83
|
+
|
|
84
|
+
A posture is what to *expect*, never what is recorded: `stage --license`
|
|
85
|
+
carries the licence as actually found at fetch time and the screen decides
|
|
86
|
+
on that. This only sets how promising the row is.
|
|
87
|
+
"""
|
|
88
|
+
return screener.resolve_license(_first_licence(self.posture))
|
|
89
|
+
|
|
90
|
+
@property
|
|
91
|
+
def eligible(self) -> bool:
|
|
92
|
+
return self.spdx in screener.ALLOWED_LICENSES
|
|
93
|
+
|
|
94
|
+
def to_json(self) -> dict:
|
|
95
|
+
return {
|
|
96
|
+
"source": self.name,
|
|
97
|
+
"kind": self.kind,
|
|
98
|
+
"fetch": self.fetch,
|
|
99
|
+
"licence_posture": self.posture,
|
|
100
|
+
"spdx": self.spdx,
|
|
101
|
+
"status": "archived" if self.archived else "active",
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
@dataclass
|
|
106
|
+
class Ranked:
|
|
107
|
+
source: Source
|
|
108
|
+
score: int
|
|
109
|
+
admitted: int = 0
|
|
110
|
+
rejected: int = 0
|
|
111
|
+
seen: int = 0
|
|
112
|
+
last_run: str = "never"
|
|
113
|
+
reasons: list[str] = field(default_factory=list)
|
|
114
|
+
|
|
115
|
+
@property
|
|
116
|
+
def why(self) -> str:
|
|
117
|
+
return " · ".join(self.reasons)
|
|
118
|
+
|
|
119
|
+
def to_json(self) -> dict:
|
|
120
|
+
return {
|
|
121
|
+
**self.source.to_json(),
|
|
122
|
+
"score": self.score,
|
|
123
|
+
"admitted": self.admitted,
|
|
124
|
+
"rejected": self.rejected,
|
|
125
|
+
"seen": self.seen,
|
|
126
|
+
"last_run": self.last_run,
|
|
127
|
+
"why": self.why,
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
# -- the parse --------------------------------------------------------------
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def read(path: Path) -> list[Source]:
|
|
135
|
+
"""Every real row of the source table, in the order a person wrote them."""
|
|
136
|
+
if not path.is_file():
|
|
137
|
+
return []
|
|
138
|
+
rows = _tables(path.read_text(encoding="utf-8"))
|
|
139
|
+
out: list[Source] = []
|
|
140
|
+
for columns in rows:
|
|
141
|
+
name = columns.get("source", "")
|
|
142
|
+
if not name or _placeholder(name):
|
|
143
|
+
continue
|
|
144
|
+
kind = (columns.get("kind") or "repository").strip().lower()
|
|
145
|
+
out.append(
|
|
146
|
+
Source(
|
|
147
|
+
name=name,
|
|
148
|
+
kind=kind if kind in KINDS else "repository",
|
|
149
|
+
fetch=columns.get("fetch", ""),
|
|
150
|
+
posture=columns.get("posture", ""),
|
|
151
|
+
status=columns.get("status", "") or "active",
|
|
152
|
+
)
|
|
153
|
+
)
|
|
154
|
+
return out
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def _tables(text: str) -> list[dict[str, str]]:
|
|
158
|
+
"""Rows as {column name: cell}, for every pipe table in the file.
|
|
159
|
+
|
|
160
|
+
The header row names the columns and the separator row is what proves it was a
|
|
161
|
+
header. A table with no recognised `source` column is not the source table —
|
|
162
|
+
`sources.md` also carries prose tables — so it contributes nothing.
|
|
163
|
+
"""
|
|
164
|
+
rows: list[dict[str, str]] = []
|
|
165
|
+
header: dict[int, str] | None = None
|
|
166
|
+
for line in text.splitlines():
|
|
167
|
+
line = line.strip()
|
|
168
|
+
if not line.startswith("|"):
|
|
169
|
+
header = None
|
|
170
|
+
continue
|
|
171
|
+
cells = [c.strip() for c in line.strip("|").split("|")]
|
|
172
|
+
if all(set(c) <= set("-: ") and c for c in cells):
|
|
173
|
+
continue # the separator row
|
|
174
|
+
if header is None:
|
|
175
|
+
header = _map_columns(cells)
|
|
176
|
+
continue
|
|
177
|
+
if "source" not in header.values():
|
|
178
|
+
continue
|
|
179
|
+
rows.append({header[i]: cell for i, cell in enumerate(cells) if i in header})
|
|
180
|
+
return rows
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def _map_columns(cells: list[str]) -> dict[int, str]:
|
|
184
|
+
mapping: dict[int, str] = {}
|
|
185
|
+
for index, cell in enumerate(cells):
|
|
186
|
+
label = cell.strip().lower().strip("*`")
|
|
187
|
+
for key, spellings in _HEADERS.items():
|
|
188
|
+
if label in spellings and key not in mapping.values():
|
|
189
|
+
mapping[index] = key
|
|
190
|
+
break
|
|
191
|
+
return mapping
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def _placeholder(name: str) -> bool:
|
|
195
|
+
"""The `| — | — | — |` row a table carries when it is honestly empty."""
|
|
196
|
+
return set(name) <= set("—-– ") or name.lower() in ("source", "")
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def _first_licence(posture: str) -> str:
|
|
200
|
+
"""The SPDX-looking token out of a prose posture cell.
|
|
201
|
+
|
|
202
|
+
A posture is written for a person — "Apache-2.0 per skill, some source-available"
|
|
203
|
+
— so the resolver gets the first token that could be an id rather than the
|
|
204
|
+
sentence. Everything it cannot pin down is `NONE-FOUND`, which is the same
|
|
205
|
+
answer as absent and ranks the row out.
|
|
206
|
+
"""
|
|
207
|
+
text = (posture or "").strip()
|
|
208
|
+
if not text:
|
|
209
|
+
return ""
|
|
210
|
+
for token in re.findall(r"[A-Za-z0-9][A-Za-z0-9.\-]{1,20}", text):
|
|
211
|
+
if screener.resolve_license(token) in screener.ALLOWED_LICENSES:
|
|
212
|
+
return token
|
|
213
|
+
return text
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
# -- the choice -------------------------------------------------------------
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def rank(sources: list[Source], yields: dict[str, tuple[int, int, int, str]], today: str = "") -> list[Ranked]:
|
|
220
|
+
"""Every source, best first, with the arithmetic that put it there.
|
|
221
|
+
|
|
222
|
+
`yields` is `{source: (admitted, rejected, seen, last_run)}` from the ledger.
|
|
223
|
+
Nothing here reads the network or a model: same inputs, same order.
|
|
224
|
+
"""
|
|
225
|
+
today = today or date.today().isoformat()
|
|
226
|
+
out: list[Ranked] = []
|
|
227
|
+
for source in sources:
|
|
228
|
+
admitted, rejected, seen, last_run = yields.get(source.name, (0, 0, 0, "never"))
|
|
229
|
+
score = 0
|
|
230
|
+
reasons: list[str] = []
|
|
231
|
+
|
|
232
|
+
if source.kind == "index":
|
|
233
|
+
score += 40
|
|
234
|
+
reasons.append("an index — read for links, never staged")
|
|
235
|
+
elif source.eligible:
|
|
236
|
+
score += 100
|
|
237
|
+
reasons.append(f"{source.spdx} is on the allowlist")
|
|
238
|
+
else:
|
|
239
|
+
reasons.append(f"posture `{source.posture or 'none'}` resolves to NONE-FOUND — the screen rejects it")
|
|
240
|
+
|
|
241
|
+
if source.archived:
|
|
242
|
+
score -= 30
|
|
243
|
+
reasons.append("archived — a fixed amount left in it, nothing new arriving (-30)")
|
|
244
|
+
|
|
245
|
+
decided = admitted + rejected
|
|
246
|
+
if decided:
|
|
247
|
+
rate = admitted / decided
|
|
248
|
+
score += round(50 * rate)
|
|
249
|
+
reasons.append(f"{admitted}/{decided} admitted at the door")
|
|
250
|
+
else:
|
|
251
|
+
score += 25
|
|
252
|
+
reasons.append("never yielded a decision — unknown yield")
|
|
253
|
+
|
|
254
|
+
if seen:
|
|
255
|
+
drawn = min(40, 5 * seen)
|
|
256
|
+
score -= drawn
|
|
257
|
+
reasons.append(f"{seen} already in the ledger (-{drawn})")
|
|
258
|
+
|
|
259
|
+
months = _months_since(last_run, today)
|
|
260
|
+
if months:
|
|
261
|
+
score += min(12, months)
|
|
262
|
+
reasons.append(f"last drawn {last_run}")
|
|
263
|
+
|
|
264
|
+
out.append(Ranked(source, score, admitted, rejected, seen, last_run, reasons))
|
|
265
|
+
|
|
266
|
+
return sorted(out, key=lambda r: (-r.score, r.source.name))
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def choose(ranked: list[Ranked], wanted: str = "") -> Ranked | None:
|
|
270
|
+
"""The one row this run draws from.
|
|
271
|
+
|
|
272
|
+
`wanted` forces a row by name or by unambiguous substring, because a person who
|
|
273
|
+
has a reason to draw from a particular place should not have to argue with a
|
|
274
|
+
score. Without it, the best-scoring harvestable row wins; an ineligible row is
|
|
275
|
+
never chosen, since a run that stages from it is a run that gets rejected.
|
|
276
|
+
"""
|
|
277
|
+
if wanted:
|
|
278
|
+
exact = [r for r in ranked if r.source.name == wanted]
|
|
279
|
+
if exact:
|
|
280
|
+
return exact[0]
|
|
281
|
+
partial = [r for r in ranked if wanted.lower() in r.source.name.lower()]
|
|
282
|
+
return partial[0] if len(partial) == 1 else None
|
|
283
|
+
for row in ranked:
|
|
284
|
+
if row.source.eligible or row.source.kind == "index":
|
|
285
|
+
return row
|
|
286
|
+
return None
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
def _months_since(last_run: str, today: str) -> int:
|
|
290
|
+
"""Whole months between two ISO dates. `never` is zero — untried is scored above."""
|
|
291
|
+
if not last_run or last_run == "never":
|
|
292
|
+
return 0
|
|
293
|
+
try:
|
|
294
|
+
then = date.fromisoformat(last_run)
|
|
295
|
+
now = date.fromisoformat(today)
|
|
296
|
+
except ValueError:
|
|
297
|
+
return 0
|
|
298
|
+
return max(0, (now.year - then.year) * 12 + (now.month - then.month))
|