Coverage for packages/workshop/src/livery/workshop/testing/_conformance.py: 96%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/ty, packages/extensions/ruff, packages/extensions/python, packages/extensions/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/mkdocstrings, packages/extensions/lfs, packages/extensions/docs, packages/extensions/cpp, packages/extensions/coverage, packages/extensions/conan, packages/extensions/cmake, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright ran.

1"""The conformance clauses, the subject they judge, and the violations they name."""
2
3from __future__ import annotations(empty)
4
5import contextlib(empty)
6import io(empty)
7import re(empty)
8import tempfile(empty)
9import threading(empty)
10import tomllib(empty)
11from collections.abc import Callable(empty)
12from dataclasses import dataclass, replace(empty)
13from pathlib import Path(empty)
14from typing import TYPE_CHECKING, Any, cast(empty)
15
16from livery.workshop import _steps(empty)
17from livery.workshop._categories import ((empty)
18 BASE_TABLE,
19 CategoryError,
20 CategoryRule,
21 category_of,
22 category_rules,
23 matches,
24)
25from livery.workshop._composition import extension_set(empty)
26from livery.workshop._fragments import Fragment, package_fragment(empty)
27from livery.workshop._packages import Package(empty)
28from livery.workshop._phases import PhaseContext(empty)
29from livery.workshop._steps import ((empty)
30 BASE_EXTENSION,
31 WORKSPACE,
32 StepRecord,
33 answering,
34 installed_step,
35 steps_by_name,
36)
37
38if TYPE_CHECKING:(empty)
39 from livery.workshop._declaration import (
40 Additions,
41 Declaration,
42 DeclaredTemplate,
43 Reference,
44 )
45
46
47@dataclass(frozen=True)(empty)
48class Subject:(empty)
49 """What an extension registers, as the kit judges it.
50
51 The records are the ones the extension registered, and the kit reads
52 the registries as they stand, so the extension's registrations run
53 before the kit does.
54
55 Attributes:
56 extension: The extension's package, ``acme.extension``: where its
57 ``extension.toml`` sits, which the kit reads as the mount
58 does.
59 sets: The sets of extensions the kit probes, each as the list a
60 package writes for it, ``("acme",)``. The
61 category-table clause judges a package listing each, and the
62 gate's walk runs over a workspace holding one such package
63 for each.
64 steps: The steps the extension registers.
65 """
66
67 extension: str(empty)
68 sets: tuple[tuple[str, ...], ...] = ()(empty)
69 steps: tuple[StepRecord, ...] = ()(empty)
70
71
72@dataclass(frozen=True)(empty)
73class Violation:(empty)
74 """One way a subject breaks a clause.
75
76 Attributes:
77 clause: The clause's name.
78 where: What the violation concerns: a set, a step, a file or
79 a path.
80 reason: What is wrong, and what the gate does because of it.
81 """
82
83 clause: str(empty)
84 where: str(empty)
85 reason: str(empty)
86
87 def __str__(self) -> str:(empty)
88 """The violation as one line: clause, what it concerns, reason."""
89 return f"{self.clause}: {self.where}: {self.reason}"
90
91
92@dataclass(frozen=True)(empty)
93class Clause:(empty)
94 """One thing the gate relies on of what an extension registers.
95
96 Attributes:
97 name: The clause's name, ``fragment-owner``.
98 rule: The rule in one sentence.
99 judge: The violations a subject commits; empty when it conforms.
100 """
101
102 name: str(empty)
103 rule: str(empty)
104 judge: Callable[[Subject], list[Violation]](empty)
105
106
107FRAGMENT_OWNER = "fragment-owner"(empty)
108CATEGORY_TABLE = "category-table"(empty)
109STEP_ORDER = "step-order"(empty)
110DECLARATION_VALIDATES = "declaration-validates"(empty)
111REFERENCES_REGISTER_NOTHING = "references-register-nothing"(empty)
112ENTRIES_NAME_DEFINED_TASKS = "entries-name-defined-tasks"(empty)
113CLAIMS_NAME_CATEGORIES = "claims-name-categories"(empty)
114WORDS_ARE_ANSWERABLE = "words-are-answerable"(empty)
115PLUGIN_IS_AN_ENTRY_POINT = "plugin-is-an-entry-point"(empty)
116REQUIREMENTS_IN_METADATA = "requirements-in-metadata"(empty)
117DECLARATION_DOCUMENTED = "declaration-documented"(empty)
118TEMPLATE_COMPOSES = "template-composes"(empty)
119FRAGMENT_DRIFT = "fragment-drift"(empty)
120WITHDRAWN_FILE = "withdrawn-file"(empty)
121WALK_ORDER = "walk-order"(empty)
122GATE_LINES = "gate-lines"(empty)
123
124
125# One owner for a per-package file.
126
127
128def _fragment_owners(extension: str, file: str) -> list[str]:(empty)
129 """The steps carrying a fragment for *file* that names *extension*, by name."""
130 return sorted(
131 name
132 for name, record in steps_by_name().items()
133 for fragment in record.fragments
134 if fragment.file == file and extension in fragment.extensions
135 )
136
137
138def _fragment_owner(subject: Subject) -> list[Violation]:(empty)
139 violations: list[Violation] = []
140 files = sorted(
141 {
142 fragment.file
143 for record in steps_by_name().values()
144 for fragment in record.fragments
145 if fragment.extensions
146 }
147 )
148 named = dict.fromkeys(
149 extension
150 for record in subject.steps
151 for fragment in record.fragments
152 for extension in fragment.extensions
153 )
154 for extension in named:
155 for file in files:
156 owners = _fragment_owners(extension, file)
157 if len(owners) > 1:
158 violations.append(
159 Violation(
160 FRAGMENT_OWNER,
161 f"extension {extension} {file}",
162 f"{' and '.join(owners)} both carry it for the extension's"
163 " packages; the render picks one by name, so one of them"
164 " yields",
165 )
166 )
167 return violations
168
169
170# The category tables.
171
172
173def _representative(pattern: str) -> str:(empty)
174 """A path *pattern* claims: each ``**`` one directory, each wildcard one letter."""
175 parts = [
176 "a" if segment == "**" else segment.replace("*", "x").replace("?", "y")
177 for segment in pattern.split("/")
178 ]
179 return "/".join(parts)
180
181
182def _documented_answer(held: tuple[str, ...], path: str) -> list[CategoryRule]:(empty)
183 """The rule the documented order picks for *path*, or the rules that tie.
184
185 *held* is the package's set of extensions. The most specific pattern
186 wins; between tables of equal specificity the nearer table wins, the
187 extension later in composition order first and the base's table
188 last; two rules of one table and one specificity claiming *path* for
189 different categories or extensions tie.
190 """
191 from livery.workshop._composition import order_or_sorted
192 from livery.workshop._extensions import installed_declaration
193
194 nearest_first = [
195 *reversed(order_or_sorted(held, installed_declaration)),
196 BASE_TABLE,
197 ]
198 matching = [rule for rule in category_rules(held) if matches(rule.pattern, path)]
199 if not matching:199 ↛ 200line 199 didn't jump to line 200 because the condition on line 199 was never true
200 return []
201 top = max(rule.specificity for rule in matching)
202 best = [rule for rule in matching if rule.specificity == top]
203 depth = min(nearest_first.index(rule.table) for rule in best)
204 at_nearest = [rule for rule in best if nearest_first.index(rule.table) == depth]
205 first = at_nearest[0]
206 if any(
207 rule.category != first.category or rule.extension != first.extension
208 for rule in at_nearest
209 ):
210 return at_nearest
211 return [first]
212
213
214def _set_name(listed: tuple[str, ...]) -> str:(empty)
215 """*listed* as a violation names it: its names joined with ``+``, or none."""
216 return "+".join(listed) or "none"
217
218
219def _category_table(subject: Subject) -> list[Violation]:(empty)
220 violations: list[Violation] = []
221 for listed in subject.sets:
222 probe = Package(
223 Path("."),
224 "packages/probe",
225 "probe",
226 (),
227 extensions=listed,
228 )
229 held = extension_set(probe)
230 for rule in category_rules(held):
231 path = _representative(rule.pattern)
232 if not matches(rule.pattern, path):
233 continue
234 where = f"set {_set_name(listed)} {path}"
235 wanted = _documented_answer(held, path)
236 if len(wanted) > 1:
237 first, second = wanted[0], wanted[1]
238 violations.append(
239 Violation(
240 CATEGORY_TABLE,
241 where,
242 f"{first.pattern!r} ({first.category}, {first.extension}) and"
243 f" {second.pattern!r} ({second.category}, {second.extension})"
244 " claim it at one specificity in one table; one of them"
245 " names the file more closely",
246 )
247 )
248 continue
249 try:
250 found = category_of(probe, path)
251 except CategoryError as error:
252 violations.append(
253 Violation(
254 CATEGORY_TABLE,
255 where,
256 f"refuses ({error}) where the nearer table's rule decides",
257 )
258 )
259 continue
260 rule_wanted = wanted[0]
261 if (found.name, found.pattern, found.supplier) != (261 ↛ 266line 261 didn't jump to line 266 because the condition on line 261 was never true
262 rule_wanted.category,
263 rule_wanted.pattern,
264 rule_wanted.extension,
265 ):
266 violations.append(
267 Violation(
268 CATEGORY_TABLE,
269 where,
270 f"answers {found.name} from {found.pattern!r}"
271 f" ({found.supplier}); the most specific rule of the"
272 f" nearest table, {rule_wanted.table}, says"
273 f" {rule_wanted.category} from {rule_wanted.pattern!r}"
274 f" ({rule_wanted.extension})",
275 )
276 )
277 return list(dict.fromkeys(violations))
278
279
280# The order of an extension's steps.
281
282
283def _loop(start: str) -> list[str]:(empty)
284 """The steps from *start* back to itself through ``after``; empty without one."""
285 records = steps_by_name()
286
287 def visit(name: str, path: list[str], seen: set[str]) -> list[str]:
288 record = records.get(name)
289 if record is None:289 ↛ 290line 289 didn't jump to line 290 because the condition on line 289 was never true
290 return []
291 for earlier in record.after:
292 target = answering(earlier)
293 if target is None:
294 continue
295 if target == start:
296 return [*path, target]
297 if target in seen:297 ↛ 298line 297 didn't jump to line 298 because the condition on line 297 was never true
298 continue
299 seen.add(target)
300 found = visit(target, [*path, target], seen)
301 if found:
302 return found
303 return []
304
305 return visit(start, [], {start})
306
307
308def _step_order(subject: Subject) -> list[Violation]:(empty)
309 violations: list[Violation] = []
310 for record in subject.steps:
311 where = f"step {record.name}"
312 for earlier in record.after:
313 # A step an installed extension declares orders nothing
314 # while the workspace does not mount it, and the gate goes on.
315 if answering(earlier) is None and not installed_step(earlier):
316 violations.append(
317 Violation(
318 STEP_ORDER,
319 where,
320 f"runs after {earlier}, which no registered step"
321 " answers to and no installed extension declares;"
322 " the gate stops there",
323 )
324 )
325 loop = _loop(record.name)
326 if loop:
327 violations.append(
328 Violation(
329 STEP_ORDER,
330 where,
331 f"runs after itself through {', '.join(loop)}; the gate"
332 " would wait on it for ever",
333 )
334 )
335 return violations
336
337
338# An extension's declaration file.
339
340
341def _listed_name(subject: Subject) -> str:(empty)
342 """The name an installed distribution declares the subject's extension under.
343
344 The package's own without one. The kit reads the declaration under
345 it, as the mount does, so a phase the file declares is the
346 extension's own and never another extension's.
347 """
348 from livery.workshop._extensions import extension_package, installed_extensions
349
350 named = [
351 name
352 for name in installed_extensions()
353 if extension_package(name) == subject.extension
354 ]
355 return named[0] if named else subject.extension
356
357
358def _declaration_validates(subject: Subject) -> list[Violation]:(empty)
359 from livery.workshop._declaration import DeclarationError, declaration_file, read
360
361 if declaration_file(subject.extension) is None:
362 return []
363 try:
364 read(_listed_name(subject), subject.extension)
365 except DeclarationError as error:
366 return [
367 Violation(
368 DECLARATION_VALIDATES,
369 f"extension {subject.extension}",
370 f"{error}; the mount refuses the extension",
371 )
372 ]
373 return []
374
375
376def _declared_of(subject: Subject) -> tuple[Path, Declaration] | None:(empty)
377 """The subject's declaration file and what it declares; None without one.
378
379 None as well for a file that refuses, which ``declaration-validates``
380 names: the clauses that read a declaration judge only one that reads.
381 """
382 from livery.workshop._declaration import DeclarationError, declaration_file, read
383
384 path = declaration_file(subject.extension)
385 if path is None:
386 return None
387 try:
388 declared = read(_listed_name(subject), subject.extension)
389 except DeclarationError:
390 return None
391 return None if declared is None else (path, declared)
392
393
394def _additions_of(declared: Declaration) -> list[tuple[tuple[str, ...], Additions]]:(empty)
395 """The top level's additions, then each ``[for.<target>]``'s, with their keys."""
396 tables: list[tuple[tuple[str, ...], Additions]] = [((), declared.additions)]
397 tables += [(("for", target), table) for target, table in declared.targets.items()]
398 return tables
399
400
401def _references(declared: Declaration) -> list[tuple[str, Reference]]:(empty)
402 """Each reference *declared* names, with the key that names it."""
403 from livery.workshop._contract_keys import shown
404 from livery.workshop._declaration import Reference
405
406 found: list[tuple[str, object]] = []
407 for prefix, additions in _additions_of(declared):
408 for record in additions.steps:
409 where = shown((*prefix, "phases", record.phase, record.step))
410 found += [(f"{where}.main", record.run), (f"{where}.fix", record.fix)]
411 if record.inputs is not None:
412 found.append((f"{where}.inputs.widen", record.inputs.widen))
413 for item in additions.jobs:
414 where = shown((*prefix, "ci", "jobs", item.point, item.job.name))
415 found += [
416 (f"{where}.installs", item.job.installs),
417 (f"{where}.labels", item.job.labels),
418 (f"{where}.deploy", item.job.deploy),
419 ]
420 found += [
421 (f"{shown(('queries', name))}.combine", spec.combine)
422 for name, spec in declared.query_specs.items()
423 ]
424 found += [
425 (f"{shown(('fragments', output.target))}.render", output.render)
426 for output in declared.fragments
427 ]
428 registered = {id(record) for record in declared.additions.steps}
429 for phase, records in declared.phases.items():
430 for record in records:
431 if id(record) in registered:
432 continue # named above, with the additions
433 where = shown(("phases", phase, record.step))
434 found += [(f"{where}.main", record.run), (f"{where}.fix", record.fix)]
435 found += [
436 (shown(("queries", name)), reference)
437 for name, reference in declared.queries.items()
438 ]
439 found += [
440 (shown(("for", target, "queries", name)), reference)
441 for target, answered in declared.target_queries.items()
442 for name, reference in answered.items()
443 ]
444 return [(key, value) for key, value in found if isinstance(value, Reference)]
445
446
447def _registered_by_import(module: str) -> list[str]:(empty)
448 """What importing *module* registers, in a process of its own."""
449 import json
450 import os
451 import sys
452
453 import livery.footman as footman
454
455 path = os.pathsep.join(entry for entry in sys.path if entry)
456 result = footman.run(
457 [sys.executable, "-m", "livery.workshop.testing._import_probe", module],
458 env={**os.environ, "PYTHONPATH": path},
459 nofail=True,
460 )
461 if result.code != 0:461 ↛ 462line 461 didn't jump to line 462 because the condition on line 461 was never true
462 lines = result.stderr.strip().splitlines()
463 return [f"its import fails: {lines[-1] if lines else result.code}"]
464 return [str(line) for line in json.loads(result.stdout)]
465
466
467def _references_register_nothing(subject: Subject) -> list[Violation]:(empty)
468 found = _declared_of(subject)
469 if found is None:
470 return []
471 named: dict[str, list[str]] = {}
472 for key, reference in _references(found[1]):
473 named.setdefault(reference.module, []).append(key)
474 violations: list[Violation] = []
475 for module, keys in named.items():
476 added = _registered_by_import(module)
477 if added:
478 violations.append(
479 Violation(
480 REFERENCES_REGISTER_NOTHING,
481 f"{module}, named by {', '.join(keys)}",
482 f"importing it registers {'; '.join(added)}; the mount"
483 " registers what the declaration says, so a reference's"
484 " module only defines",
485 )
486 )
487 return violations
488
489
490def _entries_name_defined_tasks(subject: Subject) -> list[Violation]:(empty)
491 import difflib
492
493 from livery.workshop._contract_keys import shown
494 from livery.workshop._declaration import defined_tasks
495
496 found = _declared_of(subject)
497 if found is None:
498 return []
499 path, declared = found
500 jobs = [
501 (prefix, item)
502 for prefix, additions in _additions_of(declared)
503 for item in additions.jobs
504 ]
505 if not jobs:
506 return []
507 defined = sorted(defined_tasks(path.parent))
508 violations: list[Violation] = []
509 for prefix, item in jobs:
510 where = shown((*prefix, "ci", "jobs", item.point, item.job.name, "entries"))
511 for entry in item.entries:
512 if entry.task in defined:
513 continue
514 if not defined:
515 reason = f"names {entry.task}, and the extension defines no task"
516 else:
517 near = difflib.get_close_matches(entry.task, defined, n=1)
518 hint = f"; did you mean {near[0]!r}?" if near else ""
519 reason = (
520 f"names {entry.task}, which the extension does not define{hint}"
521 )
522 violations.append(Violation(ENTRIES_NAME_DEFINED_TASKS, where, reason))
523 return violations
524
525
526def _words_are_answerable(subject: Subject) -> list[Violation]:(empty)
527 from livery.workshop._contract_keys import shown
528 from livery.workshop._steps import PACKAGE, PACKAGES
529 from livery.workshop._words import PACKAGE_PLACEHOLDERS, PLACEHOLDERS
530
531 found = _declared_of(subject)
532 if found is None:
533 return []
534 violations: list[Violation] = []
535 for prefix, additions in _additions_of(found[1]):
536 for record in additions.steps:
537 words = record.words
538 if words is None:
539 continue
540 where = shown((*prefix, "phases", record.phase, record.step))
541 reasons: list[str] = []
542 if words.tool not in record.tools:
543 reasons.append(
544 f"runs {words.tool}, which its tools do not name"
545 f" ({', '.join(record.tools) or 'none'}); a step runs a tool"
546 " it requires"
547 )
548 reasons += [
549 f"names {{{name}}}, which neither the engine nor its matrix"
550 f" answers; the engine answers {', '.join(PLACEHOLDERS)}"
551 for name in words.unanswered()
552 ]
553 reasons += [
554 f"varies {key} in its matrix, which no word names; every call"
555 " would run the same words"
556 for key in words.unvaried()
557 ]
558 if record.scope != PACKAGE and record.narrowing != PACKAGES:
559 reasons += [
560 f"names {{{name}}}, which only a call that judges one package"
561 " answers, and the step judges the workspace whole"
562 for name in PACKAGE_PLACEHOLDERS
563 if name in words.placeholders()
564 ]
565 violations += [
566 Violation(WORDS_ARE_ANSWERABLE, where, reason) for reason in reasons
567 ]
568 return violations
569
570
571def _claims_name_categories(subject: Subject) -> list[Violation]:(empty)
572 import difflib
573
574 from livery.workshop._categories import known_categories
575 from livery.workshop._contract_keys import shown
576
577 found = _declared_of(subject)
578 if found is None:
579 return []
580 known = sorted(known_categories())
581 violations: list[Violation] = []
582 for prefix, additions in _additions_of(found[1]):
583 for record in additions.steps:
584 where = shown((*prefix, "phases", record.phase, record.step, "claims"))
585 for claim in record.claims:
586 if claim.category not in known:
587 near = difflib.get_close_matches(claim.category, known, n=1)
588 hint = f"; did you mean {near[0]!r}?" if near else ""
589 violations.append(
590 Violation(
591 CLAIMS_NAME_CATEGORIES,
592 where,
593 f"names the category {claim.category!r}, which the"
594 f" workshop does not know{hint}; the step claims no"
595 " file of it",
596 )
597 )
598 violations += [
599 Violation(
600 CLAIMS_NAME_CATEGORIES,
601 where,
602 f"names the suffix {suffix!r}; a suffix starts with a dot,"
603 f" {'.' + suffix!r}",
604 )
605 for suffix in claim.suffixes
606 if not suffix.startswith(".")
607 ]
608 return violations
609
610
611def _plugin_is_an_entry_point(subject: Subject) -> list[Violation]:(empty)
612 from livery.footman import installed_entry_points
613
614 found = _declared_of(subject)
615 if found is None or not found[1].plugin:
616 return []
617 plugin = found[1].plugin
618 if plugin in {entry.name for entry in installed_entry_points("footman.tasks")}:
619 return []
620 return [
621 Violation(
622 PLUGIN_IS_AN_ENTRY_POINT,
623 f"extension {subject.extension}",
624 f"names the plugin {plugin!r}, which no installed distribution"
625 " declares in footman.tasks; the mount cannot mount its verbs",
626 )
627 ]
628
629
630#: A requirement's distribution, at the start of a ``Requires-Dist`` line.
631_REQUIRED = re.compile(r"\s*([A-Za-z0-9][A-Za-z0-9._-]*)")(empty)
632#: An extra a ``Requires-Dist`` line's marker names.
633_EXTRA = re.compile(r"""\bextra\s*==\s*["']([^"']+)["']""")(empty)
634
635
636def _required(lines: list[str]) -> list[tuple[str, frozenset[str]]]:(empty)
637 """Each ``Requires-Dist`` line as its distribution and the extras its marker names.
638
639 Both in the packaging standards' normal form. The core metadata
640 format is a published standard, so reading it pins no tool's text.
641 """
642 from livery.workshop._extensions import normal_name
643
644 found: list[tuple[str, frozenset[str]]] = []
645 for line in lines:
646 named = _REQUIRED.match(line)
647 if named is None:
648 continue
649 marker = line.partition(";")[2]
650 extras = frozenset(normal_name(extra) for extra in _EXTRA.findall(marker))
651 found.append((normal_name(named.group(1)), extras))
652 return found
653
654
655def _requirements_in_metadata(subject: Subject) -> list[Violation]:(empty)
656 from livery.workshop._extensions import (
657 distribution_of,
658 normal_name,
659 shipping_distribution,
660 ships_elsewhere,
661 )
662
663 found = _declared_of(subject)
664 if found is None:
665 return []
666 declared = found[1]
667 if not declared.requires:
668 return []
669 where = f"extension {subject.extension}"
670 dist = shipping_distribution(subject.extension)
671 if dist is None:
672 return [
673 Violation(
674 REQUIREMENTS_IN_METADATA,
675 where,
676 "declares requires, and no installed distribution declares it in"
677 " workshop.extensions, so its wheel's metadata cannot be read",
678 )
679 ]
680 required = _required(list(dist.requires or ()))
681 violations: list[Violation] = []
682 # A target the same wheel ships is held to it by being in it.
683 requires = [name for name in declared.requires if ships_elsewhere(name, dist.name)]
684 for target in requires:
685 wanted = normal_name(distribution_of(target))
686 if (wanted, frozenset()) not in required:
687 violations.append(
688 Violation(
689 REQUIREMENTS_IN_METADATA,
690 where,
691 f"requires {target}, and its wheel does not depend on"
692 f" {distribution_of(target)}; a requires range is a dependency"
693 " of the wheel, so the resolver holds the two to it",
694 )
695 )
696 return violations
697
698
699def _declaration_documented(subject: Subject) -> list[Violation]:(empty)
700 """Each item the subject's declaration names without its doc line, one each.
701
702 Read from the file as it is written, so a doc missing beside another
703 refusal is named too; a file that does not parse names nothing here,
704 since ``declaration-validates`` names it. The verbs are the tasks
705 the sources beside the file define, read when ``[extension]`` names
706 a plugin.
707 """
708 from livery.workshop._contract_keys import shown
709 from livery.workshop._declaration import (
710 DeclarationError,
711 _step_tables, # pyright: ignore[reportPrivateUsage]
712 contract_keys,
713 declaration_file,
714 task_docs,
715 )
716
717 path = declaration_file(subject.extension)
718 if path is None:
719 return []
720 try:
721 data = tomllib.loads(path.read_text("utf-8"))
722 except tomllib.TOMLDecodeError:
723 return []
724 where = f"extension {subject.extension}"
725 reasons: list[str] = []
726 identity = _table(data.get("extension"))
727 if not _documented(identity.get("description")):
728 reasons.append(
729 "declares no [extension] description; the agent's guidance and the"
730 " site say what the extension does from it"
731 )
732 if identity.get("plugin"):
733 reasons += [
734 f"defines the verb {task} with no docstring; its help, the agent's"
735 " guidance and the site show the verb by the docstring's first line"
736 for task, doc in sorted(task_docs(path.parent).items())
737 if not doc
738 ]
739 try:
740 keys = contract_keys(subject.extension)
741 except DeclarationError:
742 keys = ()
743 reasons += [
744 f"declares the {item.contract} contract key {item.path} with no doc; the"
745 " editor, the agent's guidance and the site show a key by its doc"
746 for item in keys
747 if not item.doc
748 ]
749 reasons += [
750 f"declares the template {name} with no doc; fm new.package.{name}, the"
751 " agent's guidance and the site show a template by its doc"
752 for name, table in _table(data.get("templates")).items()
753 if not _documented(_table(table).get("doc"))
754 ]
755 reasons += [
756 f"declares the option {option} of the template {name} with no doc;"
757 f" fm new.package.{name}'s help and completion, the agent's guidance and"
758 " the site show an option by its doc"
759 for name, table in _table(data.get("templates")).items()
760 for option, spec in _table(_table(table).get("options")).items()
761 if not _documented(_table(spec).get("doc"))
762 ]
763 reasons += [
764 f"declares the environment variable {name} with no doc; the agent's"
765 " guidance and the site show a variable by its doc, and the entry"
766 " script says it when the value replaces the environment's"
767 for name, table in _table(data.get("env")).items()
768 if not _documented(_table(table).get("doc"))
769 ]
770 for prefix, held in _step_holders(data):
771 for phase, table in _table(held.get("phases")).items():
772 for step, body in _step_tables(_table(table)).items():
773 reasons += [
774 f"declares the option {option} of"
775 f" [{shown((*prefix, 'phases', phase, step))}] with no doc;"
776 " the agent's guidance and the site show an option by its doc"
777 for option, spec in _table(body.get("options")).items()
778 if not _documented(_table(spec).get("doc"))
779 ]
780 return [Violation(DECLARATION_DOCUMENTED, where, reason) for reason in reasons]
781
782
783def _table(value: object) -> dict[str, Any]:(empty)
784 """*value* when it is a table, else an empty one."""
785 return cast("dict[str, Any]", value) if isinstance(value, dict) else {}
786
787
788def _documented(doc: object) -> bool:(empty)
789 """Whether *doc* is a doc line: text with something in it."""
790 return isinstance(doc, str) and bool(doc.strip())
791
792
793def _step_holders((empty)
794 data: dict[str, Any],
795) -> list[tuple[tuple[str, ...], dict[str, Any]]]:
796 """The file's top level, then each ``[for.<target>]`` table, with its keys."""
797 found: list[tuple[tuple[str, ...], dict[str, Any]]] = [((), data)]
798 found += [
799 (("for", target), _table(table))
800 for target, table in _table(data.get("for")).items()
801 ]
802 return found
803
804
805# The templates an extension declares.
806
807
808def _own_templates(subject: Subject) -> dict[str, DeclaredTemplate]:(empty)
809 """The templates the subject's declaration file declares, by name.
810
811 The base's are those of its ``contract.toml``. A declaration file
812 that refuses declares none here: ``declaration-validates`` names
813 it. A template takes the name an installed distribution declares
814 its extension under, which a chain names, and the package's own
815 without one.
816 """
817 from livery.workshop._contract_keys import BASE_FILE
818 from livery.workshop._declaration import template_declarations, template_specs_of
819
820 if subject.extension == BASE_EXTENSION:
821 data = tomllib.loads(BASE_FILE.read_text("utf-8"))
822 return template_specs_of(data, BASE_FILE, extension=BASE_EXTENSION)
823 if _declared_of(subject) is None:
824 return {}
825 found = template_declarations(_listed_name(subject), subject.extension)
826 return {template.name: template for template in found}
827
828
829def _template_composes(subject: Subject) -> list[Violation]:(empty)
830 from livery.footman import Failed
831 from livery.workshop._composition import closure, implied
832 from livery.workshop._declaration import DeclarationError
833 from livery.workshop._extensions import GROUP, installed_declaration, why_inert
834 from livery.workshop._seeds import available_templates, chain_needs, template_chain
835
836 own = _own_templates(subject)
837 if not own:
838 return []
839 try:
840 known = {**available_templates(), **own}
841 except Failed as error:
842 return [
843 Violation(TEMPLATE_COMPOSES, f"extension {subject.extension}", str(error))
844 ]
845 violations: list[Violation] = []
846 for name, template in sorted(own.items()):
847 where = f"template {name}"
848 try:
849 members = closure(template.extensions, installed_declaration)
850 required = implied(members, installed_declaration)
851 for entry in dict.fromkeys(template.extensions):
852 if entry in required:852 ↛ 853line 852 didn't jump to line 853 because the condition on line 852 was never true
853 continue
854 if installed_declaration(entry) is None:
855 violations.append(
856 Violation(
857 TEMPLATE_COMPOSES,
858 where,
859 f"lists {entry}, which no installed distribution declares"
860 f" in {GROUP}, so nothing shows that it composes"
861 " something in a package",
862 )
863 )
864 elif why := why_inert(entry):
865 violations.append(
866 Violation(
867 TEMPLATE_COMPOSES,
868 where,
869 f"lists {entry}, which composes nothing in a package:"
870 f" {why}; fm new.package.{name} refuses to create a"
871 " package from it",
872 )
873 )
874 except DeclarationError as error:
875 violations.append(Violation(TEMPLATE_COMPOSES, where, str(error)))
876 continue
877 try:
878 chain = template_chain(name, known)
879 except Failed as error:
880 violations.append(Violation(TEMPLATE_COMPOSES, where, str(error)))
881 continue
882 violations += [
883 Violation(
884 TEMPLATE_COMPOSES,
885 where,
886 f"its chain needs {needed}, which the set of its extensions does not"
887 " hold; a package born from it holds that set alone, so no step that"
888 f" names {needed} judges it",
889 )
890 for needed in chain_needs(chain)
891 if needed not in members
892 ]
893 return violations
894
895
896# An extension's configuration files, through the workshop's own render.
897
898
899def _probe_answers() -> dict[str, Any]:(empty)
900 """The answers the kit renders an extension's fragments with.
901
902 A workspace of one python member and one native member, so a
903 fragment's loops over either run.
904 """
905 return {
906 "packages": [
907 {"dir": "probe", "name": "acme-probe", "dev": "acme-probe"},
908 {"dir": "native", "name": "acme-native"},
909 ],
910 "python_floor": "3.11",
911 "namespace_package": "acme",
912 "runner_prog": "fm",
913 "project_name": "acme",
914 }
915
916
917def _package_fragments(subject: Subject) -> list[tuple[StepRecord, Fragment]]:(empty)
918 """The subject's fragments for per-package files, each with its step."""
919 return [
920 (record, fragment)
921 for record in subject.steps
922 for fragment in record.fragments
923 if fragment.extensions
924 ]
925
926
927def _project_drift(subject: Subject) -> list[Violation]:(empty)
928 """The composed project files, judged where the subject carries fragments."""
929 from livery.workshop import _templates
930
931 owners = sorted(
932 record.name
933 for record in subject.steps
934 for fragment in record.fragments
935 if fragment.file == "pyproject.toml"
936 )
937 if not owners:
938 return []
939 try:
940 composed = _templates.compose_fragments(_probe_answers())
941 except Exception as error:
942 return [
943 Violation(FRAGMENT_DRIFT, "the project files", f"do not render: {error}")
944 ]
945 try:
946 tomllib.loads(composed.get("pyproject.toml", ""))
947 except tomllib.TOMLDecodeError as error:
948 return [
949 Violation(
950 FRAGMENT_DRIFT,
951 "pyproject.toml",
952 f"composed with the fragment of {', '.join(owners)}, it is not"
953 f" TOML: {error}",
954 )
955 ]
956 return []
957
958
959def _package_drift(fragment: Fragment) -> str:(empty)
960 """What goes wrong rendering *fragment* into a probe package; empty when nothing."""
961 from livery.workshop import _shipped_files
962
963 with tempfile.TemporaryDirectory() as scratch:
964 member = Path(scratch)
965 try:
966 _shipped_files.settle_package(member, fragment.extensions)
967 except Exception as error:
968 return f"does not render: {error}"
969 drift = _shipped_files.judge_package(member, fragment.extensions)
970 if drift:
971 return f"drifts from its own render: {drift[0]}"
972 copy = member / fragment.file
973 copy.write_bytes(b"# a hand edit\n" + copy.read_bytes())
974 if not _shipped_files.judge_package(member, fragment.extensions):
975 return "a hand edit of the rendered file is not named as drift"
976 return ""
977
978
979def _fragment_drift(subject: Subject) -> list[Violation]:(empty)
980 violations = _project_drift(subject)
981 for record, fragment in _package_fragments(subject):
982 problem = _package_drift(fragment)
983 if problem:
984 held = " or ".join(fragment.extensions)
985 where = f"step {record.name} {fragment.file} for {held}"
986 violations.append(Violation(FRAGMENT_DRIFT, where, problem))
987 return violations
988
989
990def _withdraw(record: StepRecord, fragment: Fragment, *, edited: bool) -> str:(empty)
991 """What goes wrong when *record* leaves a rendered file behind; empty when nothing.
992
993 The render writes the file into a probe package, a person edits it
994 or not, the step is withdrawn, and the render settles the file
995 again. A file another step still renders for the same extensions is
996 not withdrawn at all, and says nothing here.
997 """
998 from livery.workshop import _shipped_files
999
1000 if record.name not in steps_by_name():1000 ↛ 1001line 1000 didn't jump to line 1001 because the condition on line 1000 was never true
1001 return ""
1002 state = _steps.snapshot()
1003 with tempfile.TemporaryDirectory() as scratch:
1004 member = Path(scratch)
1005 copy = member / fragment.file
1006 try:
1007 _shipped_files.settle_package(member, fragment.extensions)
1008 if not copy.is_file():1008 ↛ 1009line 1008 didn't jump to line 1009 because the condition on line 1008 was never true
1009 return "" # it did not render: the drift clause names that
1010 if edited:
1011 copy.write_bytes(b"# a hand edit\n" + copy.read_bytes())
1012 _steps.unregister_step(record.name)
1013 if package_fragment(fragment.extensions, fragment.file) is not None:
1014 return ""
1015 _shipped_files.settle_package(member, fragment.extensions)
1016 except Exception:
1017 return "" # a render that fails is the drift clause's to name
1018 finally:
1019 _steps.restore(state)
1020 if edited and not copy.is_file():
1021 return (
1022 "an edited copy is removed once the step is withdrawn;"
1023 " contract 11 keeps it as a local override"
1024 )
1025 if not edited and copy.is_file():
1026 return (
1027 "an unedited copy stays once the step is withdrawn; contract 11"
1028 " removes it"
1029 )
1030 return ""
1031
1032
1033def _withdrawn_file(subject: Subject) -> list[Violation]:(empty)
1034 violations: list[Violation] = []
1035 for record, fragment in _package_fragments(subject):
1036 held = " or ".join(fragment.extensions)
1037 where = f"step {record.name} {fragment.file} for {held}"
1038 for edited in (False, True):
1039 problem = _withdraw(record, fragment, edited=edited)
1040 if problem:
1041 violations.append(Violation(WITHDRAWN_FILE, where, problem))
1042 return violations
1043
1044
1045# The gate's walk over an extension's steps.
1046
1047
1048class _Recorder:(empty)
1049 """The calls a probe walk makes into the subject's steps, in order."""
1050
1051 def __init__(self) -> None:(empty)
1052 self.calls: list[tuple[str, str]] = []
1053 self._lock = threading.Lock()
1054
1055 def body(self, mode: str, name: str) -> Callable[[PhaseContext], None]:(empty)
1056 def record(ctx: PhaseContext) -> None:
1057 del ctx
1058 with self._lock:
1059 self.calls.append((mode, name))
1060
1061 return record
1062
1063
1064#: A file of the probe workspace no step's claims reach.
1065_UNCLAIMED = "probe/unclaimed.probe"(empty)
1066
1067
1068def _probe_packages((empty)
1069 root: Path, sets: tuple[tuple[str, ...], ...]
1070) -> tuple[Package, ...]:
1071 """One probe package for each of *sets*, listing it.
1072
1073 So a package step finds its own.
1074 """
1075 return tuple(
1076 Package(
1077 root / "packages" / f"probe-{index}",
1078 f"packages/probe-{index}",
1079 f"probe-{index}",
1080 (),
1081 extensions=listed,
1082 )
1083 for index, listed in enumerate(sets)
1084 )
1085
1086
1087def _probed(record: StepRecord, packages: tuple[Package, ...]) -> bool:(empty)
1088 """Whether the probe workspace gives *record* something to judge."""
1089 from livery.workshop._composition import extension_set
1090
1091 if record.scope == WORKSPACE:1091 ↛ 1092line 1091 didn't jump to line 1092 because the condition on line 1091 was never true
1092 return True
1093 return any(
1094 set(record.extensions) & set(extension_set(package)) for package in packages
1095 )
1096
1097
1098def _walked(record: StepRecord) -> bool:(empty)
1099 """Whether the gate's walk judges *record*: registered, in a phase the gate runs.
1100
1101 A phase nobody declares counts as one the gate runs, so the walk
1102 clauses still judge a step that names one.
1103 """
1104 from livery.workshop._phases import declared_phases
1105
1106 spec = declared_phases().get(record.phase)
1107 return record.name in steps_by_name() and (spec is None or spec.gated)
1108
1109
1110def _probe_walk((empty)
1111 subject: Subject, *, fix: bool, named: bool
1112) -> tuple[list[tuple[str, str]], str, tuple[Package, ...]]:
1113 """Walk the gate over a probe workspace with the subject's steps recording.
1114
1115 The steps' bodies are replaced by recorders and their ``after``
1116 lists emptied, so no tool runs; the registry is restored after.
1117 *named* walks over one file no claim reaches; otherwise the walk
1118 is whole and the steps' claims are emptied, so every step reads
1119 whatever git lists around the probe. Returns the calls, the gate's
1120 output, and the probe's packages.
1121 """
1122 from livery.workshop import _quality
1123
1124 recorder = _Recorder()
1125 names = [record.name for record in subject.steps if _walked(record)]
1126 state = _steps.snapshot()
1127 out = io.StringIO()
1128 try:
1129 for record in subject.steps:
1130 if record.name not in names:
1131 continue
1132 _steps.register_step(
1133 replace(
1134 record,
1135 run=recorder.body("run", record.name),
1136 fix=None
1137 if record.fix is None
1138 else recorder.body("fix", record.name),
1139 after=(),
1140 claims=record.claims if named else (),
1141 )
1142 )
1143 with tempfile.TemporaryDirectory() as scratch:
1144 root = Path(scratch)
1145 (root / _UNCLAIMED).parent.mkdir(parents=True)
1146 (root / _UNCLAIMED).write_text("probe\n")
1147 packages = _probe_packages(root, subject.sets)
1148 ctx = PhaseContext(
1149 root=root,
1150 packages=packages,
1151 fix=fix,
1152 files=(_UNCLAIMED,) if named else (),
1153 )
1154 with contextlib.redirect_stdout(out):
1155 _quality.walk(ctx, only=frozenset(names))
1156 finally:
1157 _steps.restore(state)
1158 return recorder.calls, out.getvalue(), packages
1159
1160
1161def _walk_order(subject: Subject) -> list[Violation]:(empty)
1162 calls, _out, packages = _probe_walk(subject, fix=True, named=False)
1163 first_judge = next(
1164 (index for index, (mode, _name) in enumerate(calls) if mode == "run"), None
1165 )
1166 violations: list[Violation] = []
1167 for record in subject.steps:
1168 if not _walked(record):
1169 continue
1170 where = f"step {record.name}"
1171 fixes = [
1172 index for index, call in enumerate(calls) if call == ("fix", record.name)
1173 ]
1174 judged = ("run", record.name) in calls
1175 if record.fix is not None:
1176 if not fixes:
1177 violations.append(
1178 Violation(WALK_ORDER, where, "never rewrote under --fix")
1179 )
1180 elif first_judge is not None and fixes[-1] > first_judge:
1181 violations.append(
1182 Violation(
1183 WALK_ORDER,
1184 where,
1185 "rewrote after a judge started; every fixer runs before any"
1186 " judge",
1187 )
1188 )
1189 if judged:
1190 violations.append(
1191 Violation(
1192 WALK_ORDER,
1193 where,
1194 "judged after it rewrote; a step that rewrote is not judged"
1195 " again",
1196 )
1197 )
1198 elif not judged and _probed(record, packages):
1199 violations.append(Violation(WALK_ORDER, where, "never judged under --fix"))
1200 return violations
1201
1202
1203def _gate_lines(subject: Subject) -> list[Violation]:(empty)
1204 from livery.workshop._extensions import extension_package
1205
1206 calls, out, _packages = _probe_walk(subject, fix=False, named=True)
1207 lines = out.splitlines()
1208 violations: list[Violation] = []
1209 for record in subject.steps:
1210 if not _walked(record):
1211 continue
1212 where = f"step {record.name}"
1213 # A step names the extension by the name a contract lists, which
1214 # the installed entry point maps to the subject's package.
1215 if (
1216 subject.extension != BASE_EXTENSION
1217 and record.extension != subject.extension
1218 and extension_package(record.extension) != subject.extension
1219 ):
1220 violations.append(
1221 Violation(
1222 GATE_LINES,
1223 where,
1224 f"names {record.extension} as its extension; the gate says who"
1225 f" registered a step by it, and {subject.extension} registered"
1226 " this one",
1227 )
1228 )
1229 elif (
1230 record.extension != BASE_EXTENSION
1231 and f" {record.name}: registered by {record.extension}" not in lines
1232 ):
1233 violations.append(
1234 Violation(
1235 GATE_LINES,
1236 where,
1237 f"the gate does not name {record.extension} as the extension that"
1238 " registered it",
1239 )
1240 )
1241 said = f" {record.name}: no file it reads in the named files; not run"
1242 if said not in lines:
1243 violations.append(
1244 Violation(
1245 GATE_LINES,
1246 where,
1247 'not named when it had no file to read; the gate says "no file'
1248 ' it reads" and starts nothing',
1249 )
1250 )
1251 if any(name == record.name for _mode, name in calls):
1252 violations.append(
1253 Violation(GATE_LINES, where, "started with no file to read")
1254 )
1255 return violations
1256
1257
1258CLAUSES: tuple[Clause, ...] = ((empty)
1259 Clause(
1260 FRAGMENT_OWNER,
1261 "A per-package configuration file has one owner among the steps"
1262 " whose fragments name an extension.",
1263 _fragment_owner,
1264 ),
1265 Clause(
1266 CATEGORY_TABLE,
1267 "A path's category is the most specific rule's, the nearer table"
1268 " winning a tie between tables, the extension later in composition"
1269 " order first and the base's table last, and two rules of one table"
1270 " never tie.",
1271 _category_table,
1272 ),
1273 Clause(
1274 STEP_ORDER,
1275 "Every step a step runs after is registered or declared by an"
1276 " installed extension, and following the steps it runs after never"
1277 " leads back to it.",
1278 _step_order,
1279 ),
1280 Clause(
1281 DECLARATION_VALIDATES,
1282 "An extension's extension.toml holds only the keys the workshop declares,"
1283 " each of its type, and every reference in it names a function its"
1284 " module defines.",
1285 _declaration_validates,
1286 ),
1287 Clause(
1288 REFERENCES_REGISTER_NOTHING,
1289 "Importing a module a declaration's reference names registers nothing:"
1290 " the declaration says what the extension adds, and the mount"
1291 " registers it.",
1292 _references_register_nothing,
1293 ),
1294 Clause(
1295 ENTRIES_NAME_DEFINED_TASKS,
1296 "Every task a CI job's entries name is one the extension defines, read"
1297 " from its sources: a group and a task decorated in it.",
1298 _entries_name_defined_tasks,
1299 ),
1300 Clause(
1301 CLAIMS_NAME_CATEGORIES,
1302 "Every category a step's claims name is one the workshop knows, and"
1303 " every suffix starts with a dot.",
1304 _claims_name_categories,
1305 ),
1306 Clause(
1307 WORDS_ARE_ANSWERABLE,
1308 "A step in words runs a tool it requires, every placeholder its words"
1309 " name is one the engine or its matrix answers, every matrix key is"
1310 " named in its words, and a package's placeholder sits in a step that"
1311 " judges one package at a time.",
1312 _words_are_answerable,
1313 ),
1314 Clause(
1315 PLUGIN_IS_AN_ENTRY_POINT,
1316 "The plugin an extension.toml names is a footman.tasks entry point an"
1317 " installed distribution declares.",
1318 _plugin_is_an_entry_point,
1319 ),
1320 Clause(
1321 REQUIREMENTS_IN_METADATA,
1322 "Every extension an extension.toml requires is a dependency of its wheel.",
1323 _requirements_in_metadata,
1324 ),
1325 Clause(
1326 DECLARATION_DOCUMENTED,
1327 "An extension's extension.toml carries an [extension] description, and"
1328 " every verb its plugin defines, every contract key, template,"
1329 " template option, step option and environment variable it declares"
1330 " carries its doc line.",
1331 _declaration_documented,
1332 ),
1333 Clause(
1334 TEMPLATE_COMPOSES,
1335 "Every extension a template lists composes something in a package,"
1336 " unless another it lists requires it, and the set of the template's"
1337 " list holds every extension its chain needs.",
1338 _template_composes,
1339 ),
1340 Clause(
1341 FRAGMENT_DRIFT,
1342 "A step's fragments render, the composed pyproject.toml parses, and a"
1343 " per-package file matches its render until a person edits it, when"
1344 " the drift gate names it.",
1345 _fragment_drift,
1346 ),
1347 Clause(
1348 WITHDRAWN_FILE,
1349 "A per-package file whose step is withdrawn, and which no other step"
1350 " renders for the package's extensions, is removed when unedited and kept"
1351 " when edited.",
1352 _withdrawn_file,
1353 ),
1354 Clause(
1355 WALK_ORDER,
1356 "Under --fix every step of a phase the gate runs that has a fix mode"
1357 " rewrites before any judge starts and is not judged again, and every"
1358 " other step of such a phase is judged.",
1359 _walk_order,
1360 ),
1361 Clause(
1362 GATE_LINES,
1363 "Every step of a phase the gate runs names the extension that registered"
1364 " it, by the name a workspace lists it under, which the gate prints, and a"
1365 " step with no file to read is named and never started.",
1366 _gate_lines,
1367 ),
1368)
1369"""Every clause, in the order the kit judges them."""(empty)
1370
1371
1372def judge(subject: Subject) -> list[Violation]:(empty)
1373 """Every violation *subject* commits, clause by clause; empty when it conforms."""
1374 return [violation for clause in CLAUSES for violation in clause.judge(subject)]
1375
1376
1377def builtin_subject() -> Subject:(empty)
1378 """The workshop's own steps as a subject, for its own suite.
1379
1380 Its sets are the empty one, whose package the base's table answers
1381 for alone, and, for each installed extension that composes
1382 something in a package
1383 ([livery.workshop._extensions.composes_per_package][]), the set of
1384 that extension alone.
1385 """
1386 from livery.workshop._extensions import composes_per_package, installed_extensions
1387
1388 composing = [name for name in installed_extensions() if composes_per_package(name)]
1389 return Subject(
1390 BASE_EXTENSION,
1391 sets=((), *((name,) for name in composing)),
1392 steps=tuple(
1393 record
1394 for record in steps_by_name().values()
1395 if record.extension == BASE_EXTENSION
1396 ),
1397 )