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.
Files changed (102) hide show
  1. edify/__init__.py +19 -0
  2. edify/__main__.py +6 -0
  3. edify/_toml.py +286 -0
  4. edify/agents.py +261 -0
  5. edify/anim.py +499 -0
  6. edify/assets/commands/build.md +64 -0
  7. edify/assets/commands/plan.md +68 -0
  8. edify/assets/commands/spec.md +63 -0
  9. edify/assets/commands/tasks.md +65 -0
  10. edify/assets/commands/verify.md +67 -0
  11. edify/assets/formats/plan.example.md +455 -0
  12. edify/assets/formats/plan.format.md +128 -0
  13. edify/assets/formats/spec.example.md +483 -0
  14. edify/assets/formats/spec.format.md +116 -0
  15. edify/assets/formats/tasks.example.md +712 -0
  16. edify/assets/formats/tasks.format.md +199 -0
  17. edify/assets/harvest/harvest.md +91 -0
  18. edify/assets/harvest/sources.md +295 -0
  19. edify/assets/harvest/vocab.md +52 -0
  20. edify/assets/manifest.md +30 -0
  21. edify/assets/mcp/default-registry.md +66 -0
  22. edify/assets/skills/adversary.md +61 -0
  23. edify/assets/skills/debugger.md +64 -0
  24. edify/assets/skills/implementer-general.md +53 -0
  25. edify/assets/skills/implementer-go.md +63 -0
  26. edify/assets/skills/implementer-node.md +61 -0
  27. edify/assets/skills/implementer-postgres.md +63 -0
  28. edify/assets/skills/implementer-python.md +65 -0
  29. edify/assets/skills/implementer-react.md +65 -0
  30. edify/assets/skills/planner.md +58 -0
  31. edify/assets/skills/test-writer-node.md +64 -0
  32. edify/assets/skills/test-writer-python.md +60 -0
  33. edify/assets/skills/verifier.md +67 -0
  34. edify/assets/templates/CLAUDE.md +18 -0
  35. edify/assets.py +77 -0
  36. edify/cli.py +681 -0
  37. edify/commands/__init__.py +1 -0
  38. edify/commands/check_cmd.py +72 -0
  39. edify/commands/doctor_cmd.py +206 -0
  40. edify/commands/feedback_cmd.py +90 -0
  41. edify/commands/governance_cmd.py +65 -0
  42. edify/commands/graph_cmd.py +156 -0
  43. edify/commands/harvest_cmd.py +538 -0
  44. edify/commands/init_cmd.py +333 -0
  45. edify/commands/init_new_cmd.py +151 -0
  46. edify/commands/license_cmd.py +80 -0
  47. edify/commands/mcp_cmd.py +159 -0
  48. edify/commands/self_cmd.py +185 -0
  49. edify/commands/setup_cmd.py +79 -0
  50. edify/commands/skills_cmd.py +177 -0
  51. edify/commands/upgrade_cmd.py +178 -0
  52. edify/context.py +57 -0
  53. edify/conventions.py +275 -0
  54. edify/detect.py +313 -0
  55. edify/distribution.py +40 -0
  56. edify/errors.py +66 -0
  57. edify/feedback.py +207 -0
  58. edify/formats/__init__.py +11 -0
  59. edify/formats/check.py +573 -0
  60. edify/formats/document.py +238 -0
  61. edify/formats/finding.py +50 -0
  62. edify/formats/fix.py +114 -0
  63. edify/formats/mcp.py +126 -0
  64. edify/formats/plan.py +151 -0
  65. edify/formats/skill.py +139 -0
  66. edify/formats/spec.py +164 -0
  67. edify/formats/tasks.py +321 -0
  68. edify/governance.py +316 -0
  69. edify/graph/__init__.py +11 -0
  70. edify/graph/extract.py +351 -0
  71. edify/graph/ignore.py +107 -0
  72. edify/graph/langs/__init__.py +93 -0
  73. edify/graph/langs/ctags.py +145 -0
  74. edify/graph/langs/markdown.py +41 -0
  75. edify/graph/langs/patterns.py +361 -0
  76. edify/graph/langs/python_ast.py +154 -0
  77. edify/graph/langs/sqlish.py +86 -0
  78. edify/graph/model.py +102 -0
  79. edify/graph/queries.py +211 -0
  80. edify/graph/store.py +157 -0
  81. edify/harvest/__init__.py +28 -0
  82. edify/harvest/ledger.py +191 -0
  83. edify/harvest/screen.py +236 -0
  84. edify/harvest/sources.py +298 -0
  85. edify/host.py +345 -0
  86. edify/interview.py +354 -0
  87. edify/library.py +176 -0
  88. edify/licensing/__init__.py +30 -0
  89. edify/licensing/ed25519.py +154 -0
  90. edify/licensing/projects.py +223 -0
  91. edify/licensing/tier.py +172 -0
  92. edify/licensing/token.py +149 -0
  93. edify/paths.py +282 -0
  94. edify/selfinstall.py +244 -0
  95. edify/skills.py +108 -0
  96. edify/tsv.py +109 -0
  97. edify/ui.py +334 -0
  98. edify_agents_cli-0.2.0.dist-info/METADATA +408 -0
  99. edify_agents_cli-0.2.0.dist-info/RECORD +102 -0
  100. edify_agents_cli-0.2.0.dist-info/WHEEL +4 -0
  101. edify_agents_cli-0.2.0.dist-info/entry_points.txt +2 -0
  102. edify_agents_cli-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -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)
@@ -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))