Coverage for packages/workshop/src/livery/workshop/_extensions.py: 97%

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 extension walk: the lists in the contracts, every channel.
2
3Every extension is one kind, and two lists name them: the root
4``workshop.toml``'s ``[workspace] extensions`` and each package's
5``workshop.toml``, the extensions it is composed of. The root's list
6takes any extension, and a package's list one whose declarations
7show it composes something in a package. A list's set is
8the list and every extension it requires. The installed set is the
9root's set and every package's set: a sync installs it, and mounting
10reads it, the base first, then the installed set in composition
11order: each extension after the ones it requires, ties alphabetical.
12No list's order decides anything: each list is written in its
13canonical form, the minimal one in composition order. So a package
14installed by accident never changes a repository: discovery is the
15lists and nothing else.
16"""
17
18from __future__ import annotations(empty)
19
20import re(empty)
21import tomllib(empty)
22from dataclasses import dataclass, replace(empty)
23from pathlib import Path(empty)
24from typing import TYPE_CHECKING, Any, cast(empty)
25
26from livery.footman import cwd, prog(empty)
27from livery.workshop._composition import OrderCycle, closure, order_or_sorted(empty)
28from livery.workshop._declaration import ((empty)
29 API_VERSION,
30 FILE,
31 Additions,
32 Declaration,
33 DeclarationError,
34 declaration_file,
35 read,
36)
37
38if TYPE_CHECKING:(empty)
39 from collections.abc import Iterable
40 from importlib.metadata import Distribution, EntryPoint
41
42 from livery.toolroom.store import Spec
43 from livery.workshop._packages import Package
44 from livery.workshop._points import JobContribution
45 from livery.workshop._steps import StepRecord
46
47#: The base. Never listed and never mounted by name: importing its
48#: plugin module is the base arriving.
49SELF = "livery.workshop"(empty)
50
51#: The distribution that ships the base.
52BASE_DISTRIBUTION = SELF.replace(".", "-")(empty)
53
54#: The entry point group an extension declares itself in: its name
55#: maps to the package that ships its declaration file.
56GROUP = "workshop.extensions"(empty)
57
58
59def workspace_root(start: Path | None = None) -> Path | None:(empty)
60 """The nearest ancestor carrying the workspace's contract, or None.
61
62 The workspace contract is the marker; a checkout without one is
63 not a workspace and gets no extensions. A package's own
64 ``workshop.toml``, under ``packages/<name>/`` or
65 ``packages/<group>/<name>/`` of a workspace whose root holds a
66 contract, is passed over, so a verb run inside a package resolves
67 the workspace it belongs to. Without *start*, the search starts at
68 the running task's directory, the process's outside a run: a task
69 never reads the process's own, which a parallel run shares.
70 """
71 from livery.workshop._contract import _package_workspace
72
73 origin = (start or cwd()).resolve()
74 for candidate in (origin, *origin.parents):
75 contract = candidate / "workshop.toml"
76 if not contract.is_file():
77 continue
78 above = _package_workspace(contract)
79 if above is not None and (above / "workshop.toml").is_file():
80 continue
81 return candidate
82 return None
83
84
85def _declared() -> dict[str, EntryPoint]:(empty)
86 """Every installed extension's entry point, by name."""
87 from livery.footman import installed_entry_points
88
89 return {entry.name: entry for entry in installed_entry_points(GROUP)}
90
91
92def installed_extensions() -> tuple[str, ...]:(empty)
93 """The names installed distributions declare extensions under, sorted."""
94 return tuple(sorted(_declared()))
95
96
97def shipping_distribution(package: str) -> Distribution | None:(empty)
98 """The installed distribution whose ``workshop.extensions`` entry names *package*.
99
100 None when no installed distribution declares an extension shipped
101 from *package*.
102 """
103 for entry in _declared().values():
104 if entry.value.partition(":")[0] == package and entry.dist is not None:
105 return entry.dist
106 return None
107
108
109def normal_name(name: str) -> str:(empty)
110 """*name* as a distribution or an extra is compared: lower case, one hyphen per run.
111
112 The packaging standards' normal form: ``.``, ``_`` and ``-`` in any
113 run become one ``-``.
114 """
115 return re.sub(r"[-_.]+", "-", name).lower()
116
117
118def declaration(extension: str) -> Declaration | None:(empty)
119 """*extension*'s declaration file, read and judged; None when none is installed.
120
121 Read without importing anything of the extension: footman's
122 ``plugin()`` stays a plugin's first importer, and a step's code
123 is imported when the step runs.
124
125 Raises:
126 DeclarationError: when the package the entry point names ships
127 no declaration file, as a release written for another
128 workshop does, or the file says something this workshop
129 cannot take.
130 """
131 entry = _declared().get(extension)
132 if entry is None:
133 return None
134 package = entry.value.partition(":")[0]
135 found = read(extension, package)
136 if found is None:136 ↛ 137line 136 didn't jump to line 137 because the condition on line 136 was never true
137 raise DeclarationError(
138 f"extension {extension!r}: its entry point names {package}, which ships"
139 f" no {FILE}; install a release of the extension written for this"
140 " workshop"
141 )
142 return found
143
144
145def _readable(extension: str) -> Declaration | None:(empty)
146 """*extension*'s declaration where one can be read; None for the base or none.
147
148 An extension no installed distribution declares has none, and so
149 has one whose package ships no declaration file: the mount names
150 it, and the sync installs the one this workspace builds.
151 """
152 if extension == SELF or not ships_declaration(extension):
153 return None
154 return declaration(extension)
155
156
157def ships_declaration(extension: str) -> bool:(empty)
158 """Whether an installed distribution declares *extension* and ships its file.
159
160 False for an extension no installed distribution declares, and for
161 one whose entry point names a package without a declaration file,
162 as an install whose files moved away leaves behind.
163 """
164 entry = _declared().get(extension)
165 return (
166 entry is not None
167 and declaration_file(entry.value.partition(":")[0]) is not None
168 )
169
170
171def ships_elsewhere(target: str, distribution: str) -> bool:(empty)
172 """Whether a wheel other than *distribution* ships the extension *target*.
173
174 A relation to an extension of the same wheel needs no dependency
175 and no extra: one wheel has one version, so the two cannot drift
176 apart.
177 """
178 return normal_name(distribution_of(target)) != normal_name(distribution)
179
180
181def distribution_of(extension: str) -> str:(empty)
182 """The distribution that ships *extension*: its entry point's, else by convention.
183
184 An extension no installed distribution declares, a newborn's list
185 written before its environment exists, say, is taken at the
186 convention: an import path names its distribution with its dots as
187 hyphens, and a short name is one of the base's own family,
188 ``<namespace>-extensions-<name>``, never the index's package of
189 that bare name. An entry point whose distribution's metadata is
190 gone, moved by an install after the scan, has no name to give and
191 is taken at the convention the same way.
192 """
193 entry = _declared().get(extension)
194 name = entry.dist.name if entry is not None and entry.dist is not None else None
195 if name:
196 return name
197 if "." in extension:
198 return extension.replace(".", "-")
199 return f"{SELF.partition('.')[0]}-extensions-{extension}"
200
201
202def _workspace_table(root: Path) -> dict[str, Any] | None:(empty)
203 """The root contract's ``[workspace]``, read raw; None without a contract."""
204 contract = root / "workshop.toml"
205 if not contract.is_file():
206 return None
207 # Parsed raw on purpose: this read happens while the extensions
208 # mount, before any verb runs. The contract loader judges the same
209 # file on the first verb read.
210 workspace = tomllib.loads(contract.read_text("utf-8")).get("workspace") or {}
211 return workspace if isinstance(workspace, dict) else {}
212
213
214def missing_list(root: Path) -> str:(empty)
215 """Why *root*'s contract cannot mount for want of its list; empty with one."""
216 workspace = _workspace_table(root)
217 if workspace is None or "extensions" in workspace:
218 return ""
219 return (
220 f"{root / 'workshop.toml'}: [workspace] extensions is required; add\n"
221 "\n extensions = []\n\n"
222 "under [workspace], naming the extensions this workspace uses"
223 f" (`{prog()} doctor` lists the installed ones)"
224 )
225
226
227def listing(text: str) -> Spec:(empty)
228 """An entry of an ``extensions`` list, as the requirement grammar reads it.
229
230 An entry is a name. A spelling the grammar does not read is taken
231 whole as a name: no distribution declares it, so the mount names
232 it, and ``layering.graph`` refuses the spelling. One it reads with
233 brackets, a version or a scope is read as its name, and
234 ``layering.graph`` refuses the spelling too
235 ([livery.workshop._extensions.listing_problems][]).
236 """
237 from livery.toolroom.store import Spec, SpecError
238
239 try:
240 return Spec.parse(text, where="[workspace] extensions")
241 except SpecError:
242 return Spec(text)
243
244
245def _listed(start: Path | None) -> list[Any]:(empty)
246 """The root contract's ``[workspace] extensions`` entries, raw; empty without."""
247 root = workspace_root(start)
248 workspace = None if root is None else _workspace_table(root)
249 return list(workspace.get("extensions") or []) if workspace else []
250
251
252def enabled_steps(start: Path | None = None) -> frozenset[str]:(empty)
253 """The steps the root contract turns on, each ``<phase>.<step>``; empty without.
254
255 A step its extension declares ``enabled = false`` registers only
256 while the root contract sets ``[phases.<phase>.<step>] enabled =
257 true``. Read raw, as the list is, since the mount reads it before
258 any verb judges the contract.
259 """
260 root = workspace_root(start)
261 contract = None if root is None else root / "workshop.toml"
262 if contract is None or not contract.is_file():
263 return frozenset()
264 phases = tomllib.loads(contract.read_text("utf-8")).get("phases")
265 if not isinstance(phases, dict):
266 return frozenset()
267 found: set[str] = set()
268 for phase, steps in cast("dict[str, Any]", phases).items():
269 if not isinstance(steps, dict):269 ↛ 270line 269 didn't jump to line 270 because the condition on line 269 was never true
270 continue
271 for step, table in cast("dict[str, Any]", steps).items():
272 if isinstance(table, dict) and table.get("enabled") is True:
273 found.add(f"{phase}.{step}")
274 return frozenset(found)
275
276
277def _spelling(entry: Any) -> str:(empty)
278 """How an entry spells its extension: the string, or a table entry's ``name``."""
279 return str(entry.get("name", "")) if isinstance(entry, dict) else str(entry)
280
281
282def workspace_entries(start: Path | None = None) -> tuple[tuple[str, str], ...]:(empty)
283 """Each entry of ``[workspace] extensions`` as ``(name, distribution)``, in order.
284
285 An entry is a name, or a table ``{ name = "...", without = [...] }``.
286 Empty outside a workspace and when the contract has no list: the
287 mount refuses that, and a reader has nothing to read.
288 """
289 entries: list[tuple[str, str]] = []
290 for entry in _listed(start):
291 name = listing(_spelling(entry)).name
292 entries.append((name, distribution_of(name)))
293 return tuple(entries)
294
295
296def workspace_names(start: Path | None = None) -> tuple[str, ...]:(empty)
297 """The extensions ``[workspace] extensions`` lists, in its order."""
298 return tuple(name for name, _ in workspace_entries(start))
299
300
301def installed_declaration(name: str) -> Declaration | None:(empty)
302 """*name*'s declaration where one is installed; None otherwise.
303
304 The lookup [livery.workshop._composition][] reads the installed
305 extensions through.
306 """
307 return _readable(name)
308
309
310def composes_per_package(extension: str) -> bool:(empty)
311 """Whether *extension* composes something in a package whose set holds it.
312
313 The proof reads the installed declarations alone. *extension*
314 composes when it, or an extension it requires transitively,
315 declares at its top level or in a ``[for.<target>]`` table a step
316 in a phase whose level is ``package``, an answer to a query whose
317 level is ``package``, or ``[categories]``; or when a step of any
318 installed extension, or a step's per-package fragment, names it in
319 ``extensions``. Workspace-level steps and answers, contract keys,
320 tools, shipped files, CI jobs, verbs, templates and ``requires``
321 itself compose nothing in a package. An extension whose code alone
322 reads a package's set is not seen: the declarations define what
323 composes, so a package's list refuses such an extension. An
324 installed declaration that cannot be read names nothing.
325 """
326 from livery.workshop._phases import PACKAGE_LEVEL, declared_phases
327 from livery.workshop._queries import declared_queries
328
329 phases = declared_phases()
330 queries = declared_queries()
331 named = _named_by_steps()
332 for name in closure((extension,), installed_declaration):
333 if name in named:
334 return True
335 found = installed_declaration(name)
336 if found is None:
337 continue
338 # The read refused a step into a phase, and an answer to a query,
339 # that no installed declaration declares, so each is known here.
340 if any(340 ↛ 344line 340 didn't jump to line 344 because the condition on line 340 was never true
341 phases[record.phase].level == PACKAGE_LEVEL
342 for record in _declared_steps(found)
343 ):
344 return True
345 answered = [*found.queries]
346 for held in found.target_queries.values():
347 answered += held
348 if any(queries[query].level == PACKAGE_LEVEL for query in answered):
349 return True
350 if found.categories or any(
351 table.get("categories") for table in found.target_tables.values()
352 ):
353 return True
354 return False
355
356
357def _declared_steps(found: Declaration) -> list[StepRecord]:(empty)
358 """Every step *found* declares: its top-level tables' and its ``[for]`` tables'."""
359 records = [record for held in found.phases.values() for record in held]
360 for additions in found.targets.values():
361 records += additions.steps
362 return records
363
364
365def installed_record(name: str) -> StepRecord | None:(empty)
366 """The step *name* as an installed extension declares it; None when none does.
367
368 *name* is ``<phase>.<step>``. The installed extensions are read in
369 name order, each one's top-level tables and its ``[for.<target>]``
370 tables alike, and the first that declares the step answers, its
371 record naming it. A declaration that cannot be read declares
372 nothing here: the mount and ``layering.graph`` name it.
373 """
374 for extension in installed_extensions():
375 try:
376 found = _readable(extension)
377 except DeclarationError:
378 continue
379 if found is None:379 ↛ 380line 379 didn't jump to line 380 because the condition on line 379 was never true
380 continue
381 for record in _declared_steps(found):
382 if record.name == name:
383 return replace(record, extension=extension)
384 return None
385
386
387def _named_by_steps() -> frozenset[str]:(empty)
388 """The extensions a step of an installed extension names in ``extensions``.
389
390 A step's own list and each of its per-package fragments' lists. An
391 installed declaration that cannot be read names nothing.
392 """
393 found: set[str] = set()
394 for name in installed_extensions():
395 try:
396 declared = _readable(name)
397 except DeclarationError:
398 continue
399 if declared is None:399 ↛ 400line 399 didn't jump to line 400 because the condition on line 399 was never true
400 continue
401 for record in _declared_steps(declared):
402 found.update(record.extensions)
403 for fragment in record.fragments:
404 found.update(fragment.extensions)
405 return frozenset(found)
406
407
408def why_inert(extension: str) -> str:(empty)
409 """What *extension* does instead of composing a package; empty when it composes.
410
411 The proof is `composes_per_package`'s. For an extension that
412 composes nothing, the words say what its own steps
413 judge: every package that holds one of the extensions they name,
414 the workspace as a whole when they name none, or that it declares
415 no step. A refusal of the extension in a package's list, or in a
416 template's, reads them after ``composes nothing in a package:``.
417 """
418 if composes_per_package(extension):
419 return ""
420 found = installed_declaration(extension)
421 steps = _declared_steps(found) if found is not None else []
422 named: dict[str, None] = {}
423 for record in steps:
424 named.update(dict.fromkeys(record.extensions))
425 if named:
426 return f"its steps judge every package that holds {_either(list(named))}"
427 if steps:
428 return "its steps judge the workspace as a whole"
429 return "it declares no step"
430
431
432def _either(names: list[str]) -> str:(empty)
433 """*names* as a sentence offers them: ``a``, ``a or b``, ``a, b or c``."""
434 if len(names) < 2:
435 return "".join(names)
436 return f"{', '.join(names[:-1])} or {names[-1]}"
437
438
439def root_set(start: Path | None = None) -> tuple[str, ...]:(empty)
440 """The root's set: ``[workspace] extensions`` and what it requires.
441
442 In composition order, whatever the list's order and whether an
443 implied extension is written in it. A name no installed
444 distribution declares stays in the set and requires nothing. A
445 declared order with no start falls back to alphabetical, and
446 ``layering.graph`` names the cycle. Empty outside a workspace.
447 """
448 names = closure(workspace_names(start), installed_declaration)
449 return order_or_sorted(names, installed_declaration)
450
451
452def installed_set(start: Path | None = None) -> tuple[str, ...]:(empty)
453 """The extensions the workspace installs and mounts, in composition order.
454
455 The root's set and every package's set, each a list and every
456 extension it requires, whatever that extension declares, in
457 composition order ([livery.workshop._composition.order][]): each
458 extension after the ones it requires, ties alphabetical. Neither
459 list's order changes it. A name no installed distribution declares
460 stays in the set: the mount names it, and ``fm sync`` installs it.
461 A declared order with no start falls back to alphabetical here, so
462 a sync still runs, and ``layering.graph`` names the cycle. Empty
463 outside a workspace.
464 """
465 root = workspace_root(start)
466 if root is None:
467 return ()
468 listed = list(workspace_names(root))
469 for _contract, names in _package_lists(root):
470 listed += [listing(name).name for name in names]
471 found = closure(listed, installed_declaration)
472 return order_or_sorted(found, installed_declaration)
473
474
475def where_listed(start: Path | None = None) -> dict[str, str]:(empty)
476 """Each extension of the installed set to the list that brings it, as notes say it.
477
478 ``listed in [workspace] extensions``, ``listed in the `extensions`
479 of packages/<name>`` naming each package that lists it, or, for an
480 extension no list names, ``required by <name>`` naming the first
481 listed extension whose set holds it. Empty outside a workspace.
482 """
483 root = workspace_root(start)
484 if root is None:484 ↛ 485line 484 didn't jump to line 485 because the condition on line 484 was never true
485 return {}
486 listed = list(workspace_names(root))
487 found = dict.fromkeys(listed, "listed in [workspace] extensions")
488 packages: dict[str, dict[str, None]] = {}
489 for contract, names in _package_lists(root):
490 where = contract.parent.relative_to(root).as_posix()
491 for entry in names:
492 name = listing(entry).name
493 packages.setdefault(name, {})[where] = None
494 listed.append(name)
495 for name, places in packages.items():
496 spoken = _spoken(list(places))
497 found.setdefault(name, f"listed in the `extensions` of {spoken}")
498 for name in listed:
499 for needed in closure((name,), installed_declaration):
500 found.setdefault(needed, f"required by {name}")
501 return found
502
503
504def extension_entries(start: Path | None = None) -> tuple[tuple[str, str], ...]:(empty)
505 """Every extension of the installed set as ``(name, distribution)``, in mount order.
506
507 The set [livery.workshop._extensions.installed_set][] composes, each
508 with the distribution that ships it
509 ([livery.workshop._extensions.distribution_of][]). Empty outside a
510 workspace.
511 """
512 return tuple((name, distribution_of(name)) for name in installed_set(start))
513
514
515def stack_entries(start: Path | None = None) -> tuple[tuple[str, str], ...]:(empty)
516 """The base, then every listed extension in mount order, as name and distribution.
517
518 What a reader of the whole stack walks: the base ships the template
519 tree the extensions overlay, and composition follows the mount's
520 order. Empty outside a workspace.
521 """
522 root = workspace_root(start)
523 if root is None or not (root / "workshop.toml").is_file():
524 return ()
525 return ((SELF, SELF.replace(".", "-")), *extension_entries(start))
526
527
528def stack_names(start: Path | None = None) -> tuple[str, ...]:(empty)
529 """The base, then every listed extension: whose content a sync delivers."""
530 return tuple(name for name, _ in stack_entries(start))
531
532
533def extension_package(extension: str) -> str:(empty)
534 """The dotted package *extension* ships from: the one its entry point names.
535
536 The base is its own; an extension no installed distribution
537 declares is taken at its name, which a member mid-birth may be.
538 """
539 if extension == SELF:
540 return SELF
541 entry = _declared().get(extension)
542 if entry is None:
543 return extension
544 return entry.value.partition(":")[0]
545
546
547def extension_provider(extension: str, packages: tuple[Package, ...]) -> str:(empty)
548 """The member package whose sources ship *extension*, by its path; empty if none.
549
550 *extension* is the name it is listed by, which is no module: the
551 package its entry point names is looked up instead. An extension
552 installed from an index has no member.
553 """
554 from livery.workshop._influence import provider_of
555
556 return provider_of(extension_package(extension), packages)
557
558
559def extension_names(start: Path | None = None) -> tuple[str, ...]:(empty)
560 """The extensions the workspace installs and mounts, in mount order.
561
562 The root's set and every package's set, in composition order
563 ([livery.workshop._extensions.installed_set][]).
564 ``workspace_names`` reads the workspace list alone, and
565 ``root_set`` the root's set.
566 """
567 return installed_set(start)
568
569
570def extension_content(extension: str) -> Path | None:(empty)
571 """The installed extension's ``content/`` directory, or None.
572
573 Beside the extension's declaration file, or the base's own for
574 the base. In the monorepo the "wheel" is the editable source tree,
575 which is what lets the materialised links point back into the
576 repository. None for an extension that is not installed or ships
577 no content.
578 """
579 if extension == SELF:
580 content = base_directory() / "content"
581 return content if content.is_dir() else None
582 found = declaration(extension)
583 if found is None:
584 return None
585 content = found.path.resolve().parent / "content"
586 return content if content.is_dir() else None
587
588
589def base_directory() -> Path:(empty)
590 """The directory this process imported the base from.
591
592 The base's own files, its ``content/`` among them, are read from
593 here.
594 """
595 return Path(__file__).resolve().parent
596
597
598def shipped_content(start: Path | None = None) -> tuple[tuple[str, Path], ...]:(empty)
599 """Each extension of the workspace's stack with its ``content/`` directory.
600
601 The base first, then the installed set in mount order, each with
602 the directory its shipped files live in; an extension that ships no
603 content, or that no installed distribution declares, is left out.
604 """
605 found: list[tuple[str, Path]] = []
606 for extension in stack_names(start):
607 content = extension_content(extension)
608 if content is not None:
609 found.append((extension, content))
610 return tuple(found)
611
612
613def left_out(start: Path | None = None) -> dict[str, tuple[str, ...]]:(empty)
614 """Each root entry's ``without``: the targets its extension contributes nothing to.
615
616 Cooperation is greedy: an extension contributes to every target of
617 the installed set it declares a ``[for.<target>]`` table for, a
618 target listed later included. A table entry's ``without = [...]``
619 is the workspace's opt-out, naming the targets that get nothing
620 from it. An entry with no ``without`` leaves out nothing, and the
621 fix of ``layering.graph`` writes a table entry that leaves out
622 nothing as the name alone.
623 """
624 found: dict[str, tuple[str, ...]] = {}
625 for entry in _listed(start):
626 name = listing(_spelling(entry)).name
627 written = entry.get("without") if isinstance(entry, dict) else None
628 found[name] = (
629 tuple(str(target) for target in cast("list[object]", written))
630 if isinstance(written, list)
631 else ()
632 )
633 return found
634
635
636#: Whether mount_extensions ran in this process. The cascade hook reads
637#: it: a workspace declaring further extensions whose tasks.py never
638#: mounted them is running a pre-composition render, and the gap
639#: must teach rather than silently narrow the tree.
640MOUNTED: bool = False(empty)
641
642#: The listed extensions the last mount found no installed distribution
643#: declaring. A sync reads them before it renders anything
644#: ([livery.workshop._extensions.unmounted][]).
645UNDECLARED: tuple[str, ...] = ()(empty)
646
647#: Of those, the ones an installed distribution declares by an entry point
648#: whose package ships no declaration file: an environment from before the
649#: checkout's, which a sync's ``uv sync`` brings current.
650STALE: tuple[str, ...] = ()(empty)
651
652
653def snapshot(*, initial: bool = False) -> tuple[bool, tuple[str, ...], tuple[str, ...]]:(empty)
654 """What the mount recorded, for [livery.workshop._extensions.restore][] to put back.
655
656 Whether a mount ran, and the listed extensions it found undeclared
657 and stale. With *initial*, the record a process starts with
658 instead: no mount, and nothing found.
659 """
660 if initial:
661 return False, (), ()
662 return MOUNTED, UNDECLARED, STALE
663
664
665def restore(state: tuple[bool, tuple[str, ...], tuple[str, ...]]) -> None:(empty)
666 """Put the mount's records back to *state*."""
667 global MOUNTED, UNDECLARED, STALE
668 MOUNTED, UNDECLARED, STALE = state
669
670
671def mount_git_plugin() -> str:(empty)
672 """Mount the git plugin; the reason it could not, printed as a note, or empty.
673
674 The environment every git spawn runs with: one ssh connection per
675 host, the tools' identity, an editor that never opens. The mount
676 runs on every command, ``fm sync`` among them, which is what
677 installs the entry point a checkout that just moved past the
678 plugin's arrival lacks, so a refusal here would stop the command
679 that repairs it.
680 """
681 from livery.footman import plugin, prog
682
683 try:
684 plugin("livery.git")
685 except ValueError as error:
686 why = f"the git plugin is not mounted ({error}); `{prog()} sync` installs it"
687 _note(why)
688 return why
689 return ""
690
691
692def mount_extensions(start: Path | None = None) -> tuple[str, ...]:(empty)
693 """Mount the plugin of every extension of the installed set, in mount order.
694
695 Returns the names mounted. The installed set mounts in composition
696 order ([livery.workshop._extensions.installed_set][]), so an
697 extension finds every extension it requires already registered,
698 whatever either list's order. Any extension mounts from either
699 list. Refuses an extension declared for another workshop API
700 version, one whose declaration file says something this workshop
701 cannot take, a step into a phase of an extension it does not
702 require (``check_phase_declarers``), and a step that replaces or
703 deletes a step of an extension it does not require
704 (``check_replacements``).
705 A contract without ``[workspace] extensions``, an extension no
706 installed distribution declares, and one whose installed package
707 ships no declaration file are named on stderr, the first of these
708 with the list that brings it, and skipped, never refused:
709 the mount runs on every command, ``fm sync`` among them, which is
710 what installs a missing declaration, so a refusal here would stop
711 the command that repairs it. An entry with brackets is named the
712 same way and read as its name alone. The gate's ``layering.graph`` and
713 ``fm extensions`` refuse the same problems. An extension
714 whose declaration names no ``plugin`` registers what it declares
715 and mounts no verbs, and one that declares nothing but answers to
716 queries, at its top level or in a ``[for.<target>]`` table, is
717 mounted all the same, since the listed extensions' answers are read
718 while they are listed. A plugin a branded App already mounts as a
719 builtin is not mounted again, since claiming its tasks again puts
720 the same task in one rung twice; what its declaration adds
721 registers as any other extension's does. A dormant extension
722 ([livery.workshop._extensions.dormancy][]) registers no step and no
723 job, at its top level or in its ``[for.<target>]`` tables, and its
724 plugin mounts all the same, so its verbs stay.
725
726 Each template the base or a mounted extension's declaration declares
727 becomes a verb, ``fm new.package.<template>``
728 (`livery.workshop._templates.generate_template_verbs`), read from
729 the declarations this walk read already: a template the installed
730 set's extensions declare is offered, and no other file is read.
731 """
732 from livery.footman import builtins, plugin
733 from livery.workshop._seeds import base_templates
734
735 global MOUNTED, UNDECLARED, STALE
736 MOUNTED = True
737 undeclared: list[str] = []
738 root = workspace_root(start)
739 if root is not None and (why := missing_list(root)):
740 _note(why)
741 builtin = set(builtins())
742 mounted = []
743 stale: list[str] = []
744 declared = declared_targets(start)
745 active = resolved_targets(start)
746 enabled = enabled_steps(start)
747 contributes = _contributing(active)
748 asleep = frozenset(_dormant(tuple(active), contributes))
749 # The base is present before this walk; every extension joins once
750 # its mount ran.
751 present = [SELF]
752 grafted: set[tuple[str, str]] = set()
753 _graft_contributions(present, declared, active, grafted, enabled, asleep)
754 named: dict[str, str] | None = None
755 # The templates each declaration read below declares, the first
756 # declarer of a name kept: a birth from a name two extensions
757 # declare refuses naming both.
758 templates = dict(base_templates())
759 for extension, dist in extension_entries(start):
760 if extension in builtin:
761 # The App mounted it as its own builtin: its plugin is never
762 # mounted here a second time, and what its declaration adds
763 # registers all the same.
764 found = _readable(extension)
765 if found is not None:
766 templates = {**found.templates, **templates}
767 check_api_version(extension, found)
768 check_phase_declarers(extension, found)
769 check_replacements(extension, found)
770 if (770 ↛ 775line 770 didn't jump to line 775 because the condition on line 770 was always true
771 extension not in asleep
772 and register_declared(extension, found.additions, enabled=enabled)
773 ) or _answers_queries(found):
774 mounted.append(extension)
775 present.append(extension)
776 _graft_contributions(present, declared, active, grafted, enabled, asleep)
777 continue
778 package = extension_package(extension)
779 if extension in _declared() and declaration_file(package) is None:779 ↛ 783line 779 didn't jump to line 783 because the condition on line 779 was never true
780 # An environment from before this checkout's, or a release
781 # written for another workshop: named and skipped, so the
782 # sync that installs this checkout's can run.
783 undeclared.append(extension)
784 stale.append(extension)
785 _note(
786 f"extension {extension!r}: the installed distribution ({dist})"
787 f" names {package}, which ships no {FILE}; `{prog()} sync`"
788 " installs the one this workspace builds"
789 )
790 continue
791 found = declaration(extension)
792 if found is None:
793 undeclared.append(extension)
794 if named is None:
795 named = where_listed(start)
796 _note(
797 f"extension {extension!r} is"
798 f" {named.get(extension, 'listed')}, and no installed"
799 f" distribution declares it in {GROUP}; install the distribution"
800 f" that ships it ({dist} by its name), or remove the entry;"
801 f" `{prog()} sync` installs it the way this workspace resolves it"
802 )
803 continue
804 templates = {**found.templates, **templates}
805 check_api_version(extension, found)
806 check_phase_declarers(extension, found)
807 check_replacements(extension, found)
808 if (
809 extension not in asleep
810 and register_declared(extension, found.additions, enabled=enabled)
811 ) or _answers_queries(found):
812 mounted.append(extension)
813 name = found.plugin
814 if name and name not in builtin:
815 try:
816 plugin(name)
817 except Exception as error:
818 _note(
819 f"extension {extension!r} did not mount its plugin {name!r}:"
820 f" {error}; its distribution ({dist}) belongs in the dev"
821 f" group, and `{prog()} sync` installs it"
822 )
823 else:
824 if extension not in mounted:
825 mounted.append(extension)(empty)
826 present.append(extension)
827 _graft_contributions(present, declared, active, grafted, enabled, asleep)
828 # An extension's steps registered as it mounted; their verbs join the
829 # ones the workshop generated as it loaded.
830 from livery.workshop._steps import generate_verbs
831 from livery.workshop._templates import generate_template_verbs
832
833 generate_verbs()
834 generate_template_verbs(dict(sorted(templates.items())))
835 UNDECLARED = tuple(undeclared)
836 STALE = tuple(stale)
837 return tuple(mounted)
838
839
840def stale_declarations(start: Path | None = None) -> tuple[str, ...]:(empty)
841 """The listed extensions the mount found installed from before this checkout.
842
843 Each has an entry point whose package ships no declaration file, so
844 the environment's metadata is older than the source: ``uv sync``
845 brings it current.
846 """
847 listed = extension_names(start)
848 return tuple(name for name in STALE if name in listed)
849
850
851def unmounted(start: Path | None = None) -> tuple[str, ...]:(empty)
852 """The listed extensions the mount found no installed distribution declaring.
853
854 An extension the contract no longer lists is not counted.
855 """
856 listed = extension_names(start)
857 return tuple(name for name in UNDECLARED if name in listed)
858
859
860def declared_now(names: tuple[str, ...]) -> tuple[str, ...]:(empty)
861 """Of *names*, the extensions an installed distribution declares now.
862
863 Reads the installed entry points again, since the process scanned
864 them once at its start, and imports nothing: a distribution
865 installed after the interpreter started may not be importable in
866 it, as an editable install's path joins `sys.path` only when a
867 process starts.
868 """
869 if not names:
870 return ()
871 from livery.footman import rescan_entry_points
872
873 rescan_entry_points()
874 declared = _declared()
875 return tuple(name for name in names if name in declared)
876
877
878def install_places(names: Iterable[str]) -> dict[str, tuple[str, str, str]]:(empty)
879 """Where each of *names*, the base or an extension, is installed, as read here.
880
881 Each place is three parts: the package the extension's entry point
882 names, the declaration file this process reads for it, and the
883 origin the installer recorded in the distribution's
884 ``direct_url.json``, which is empty for a distribution from an
885 index. The file is empty when the directory this process found the
886 package in no longer holds one, and every part is empty for an
887 extension no installed distribution declares. The base, named by
888 ``SELF``, has the same three parts: its package, the directory this
889 process imported it from (empty once that directory holds no
890 ``__init__.py``), and the origin of ``BASE_DISTRIBUTION``; every
891 part is empty when no distribution of that name is installed.
892
893 Read before an install and again after it, a place that differs
894 names an extension this process cannot read where the environment
895 installs it now. The directory a package was found in is kept for
896 the process, and an editable install's path joins ``sys.path`` only
897 when a process starts. The origin tells an editable install's tree
898 that is still on disk from the tree the environment installs.
899 Imports nothing.
900 """
901 declared = _declared()
902 places: dict[str, tuple[str, str, str]] = {}
903 for name in names:
904 if name == SELF:
905 places[name] = _base_place()
906 continue
907 entry = declared.get(name)
908 if entry is None:
909 places[name] = ("", "", "")
910 continue
911 package = entry.value.partition(":")[0]
912 found = declaration_file(package)
913 dist = entry.dist
914 origin = dist.read_text("direct_url.json") if dist is not None else None
915 places[name] = (package, str(found or ""), origin or "")
916 return places
917
918
919def _base_place() -> tuple[str, str, str]:(empty)
920 """Where the base is installed, as this process reads it; see `install_places`."""
921 from importlib.metadata import PackageNotFoundError, distribution
922
923 try:
924 dist = distribution(BASE_DISTRIBUTION)
925 except PackageNotFoundError:
926 return ("", "", "")
927 directory = base_directory()
928 found = str(directory) if (directory / "__init__.py").is_file() else ""
929 return (SELF, found, dist.read_text("direct_url.json") or "")
930
931
932def _note(text: str) -> None:(empty)
933 """Name a problem the mount skips past, on stderr."""
934 import sys
935
936 print(f" note: {text}", file=sys.stderr)
937
938
939def _reached(extension: str, found: Declaration) -> frozenset[str]:(empty)
940 """The owners whose steps *extension*'s top-level tables may reach.
941
942 The base, *extension* itself and every extension it requires,
943 transitively: each is in every set that holds *extension*, and
944 mounts before it. A ``[for.<target>]`` table reaches its target as
945 well, since the table registers once both are mounted.
946 """
947 return frozenset({SELF, extension, *closure(found.requires, installed_declaration)})
948
949
950def check_phase_declarers(extension: str, found: Declaration) -> None:(empty)
951 """Refuse a step of *extension* into a phase of an extension it does not require.
952
953 A phase is declared by the base or by an extension. A step of
954 *extension*'s top-level tables goes into a phase the base,
955 *extension* itself or an extension it requires declares; a step of
956 a ``[for.<target>]`` table also into one *target* declares. Judged
957 from the declarations alone, every ``[for]`` table whether it
958 applies or not, so the verdict follows no list and no list's order.
959
960 Raises:
961 Failed: naming the extension, the phase and its declarer, with
962 the two ways to write the step.
963 """
964 from livery.footman import fail
965 from livery.workshop import _phases
966
967 reached = _reached(extension, found)
968 added = {
969 (phase, reached)
970 for phase in (
971 *(record.phase for record in found.additions.steps),
972 *found.phases,
973 )
974 }
975 for target, additions in found.targets.items():
976 added |= {(record.phase, reached | {target}) for record in additions.steps}
977 specs = _phases.declared_phases()
978 for phase, allowed in sorted(added, key=lambda pair: (pair[0], sorted(pair[1]))):
979 declarer = specs[phase].extension if phase in specs else SELF
980 if declarer not in allowed:
981 fail(
982 f"extension {extension!r} adds steps to the {phase} phase, which"
983 f" {declarer} declares, and does not require {declarer}; add"
984 f" {declarer} to its [extension] requires, or move the steps into"
985 f" [for.{declarer}]"
986 )
987
988
989def check_replacements(extension: str, found: Declaration) -> None:(empty)
990 """Refuse a step of *extension* that replaces or deletes one it cannot reach.
991
992 A step names each step it replaces or deletes as
993 ``<owner>:<phase>.<step>``. In *extension*'s top-level tables the
994 owner is the base or an extension *extension* requires, so the
995 owner's step registers first in every set that holds both; in a
996 ``[for.<target>]`` table it may also be *target*. Judged from the
997 declarations alone, whatever the lists hold or their order.
998
999 Raises:
1000 Failed: naming the step, the one it replaces or deletes, and the
1001 two ways to write it.
1002 """
1003 from livery.footman import fail
1004
1005 reached = _reached(extension, found)
1006 tables: list[tuple[frozenset[str], list[StepRecord]]] = [
1007 (
1008 reached,
1009 [
1010 *found.additions.steps,
1011 *(record for held in found.phases.values() for record in held),
1012 ],
1013 )
1014 ]
1015 tables += [
1016 (reached | {target}, list(additions.steps))
1017 for target, additions in found.targets.items()
1018 ]
1019 for allowed, records in tables:
1020 for record in records:
1021 for verb, named in (
1022 ("replaces", record.replaces),
1023 ("deletes", record.deletes),
1024 ):
1025 for address, _reason in named:
1026 owner = address.partition(":")[0]
1027 if owner not in allowed:
1028 fail(
1029 f"extension {extension!r}: {record.name} {verb}"
1030 f" {address}, and {extension} does not require {owner};"
1031 f" add {owner} to its [extension] requires, or move the"
1032 f" step into [for.{owner}]"
1033 )
1034
1035
1036def _graft_contributions((empty)
1037 present: list[str],
1038 declared: dict[str, dict[str, Additions]],
1039 active: dict[str, tuple[str, ...]],
1040 grafted: set[tuple[str, str]],
1041 enabled: frozenset[str] = frozenset(),
1042 asleep: frozenset[str] = frozenset(),
1043) -> None:
1044 """Register every ``[for.<target>]`` table whose owner and target are both present.
1045
1046 Called after each extension mounts, so a contribution lands whichever
1047 of the two mounts later. *active* holds each owner's targets, so a
1048 target its root entry's ``without`` names registers nothing. A step
1049 in the table declared off registers under the steps the root
1050 contract turns on, *enabled*, as one at the file's top level does.
1051 An owner among *asleep*, the dormant extensions, registers none of
1052 its tables.
1053 """
1054 for owner in present:
1055 if owner in asleep:
1056 continue
1057 for target in active.get(owner, ()):
1058 if target not in present or (owner, target) in grafted:
1059 continue
1060 additions = declared.get(owner, {}).get(target)
1061 if additions is None:1061 ↛ 1062line 1061 didn't jump to line 1062 because the condition on line 1061 was never true
1062 continue
1063 register_declared(owner, additions, enabled=enabled)
1064 grafted.add((owner, target))
1065
1066
1067def _answers_queries(found: Declaration) -> bool:(empty)
1068 """Whether *found* answers a query, at its top level or in a ``[for]`` table.
1069
1070 A ``[for]`` table's answer counts whether its target is listed or
1071 not: the mount counts what the declaration answers, and the query
1072 decides which places it asks.
1073 """
1074 return bool(found.queries or found.target_queries)
1075
1076
1077def register_declared((empty)
1078 extension: str, additions: Additions, *, enabled: frozenset[str] = frozenset()
1079) -> bool:
1080 """Register what *additions* declares for *extension*; whether it declares a step.
1081
1082 Each step registers under the extension's listed name, since the
1083 list is what decides which extension a step belongs to, and each
1084 job joins its point under the same name. A step declared
1085 ``enabled = false`` registers only when
1086 *enabled*, the steps the root contract turns on
1087 ([livery.workshop._extensions.enabled_steps][]), names it.
1088 """
1089 from dataclasses import replace
1090
1091 from livery.workshop._steps import register_step
1092
1093 for record in additions.steps:
1094 if not record.enabled and record.name not in enabled:
1095 continue
1096 register_step(replace(record, extension=extension))
1097 register_jobs(extension, additions.jobs)
1098 return bool(additions.steps)
1099
1100
1101def register_jobs(extension: str, jobs: tuple[JobContribution, ...]) -> None:(empty)
1102 """Add each of *jobs* to its builtin point, its entries' source *extension*.
1103
1104 Raises:
1105 Failed: when another extension contributed a job of the same name
1106 to the same point.
1107 """
1108 from dataclasses import replace
1109
1110 from livery.workshop._points import contribute_job
1111
1112 for item in jobs:
1113 contribute_job(
1114 item.point,
1115 item.job,
1116 entries=tuple(replace(entry, source=extension) for entry in item.entries),
1117 gates=item.gates,
1118 extension=extension,
1119 )
1120
1121
1122def check_api_version(extension: str, found: Declaration) -> None:(empty)
1123 """Refuse an extension whose declared API version is not this workshop's.
1124
1125 An extension declares ``[extension] api-version`` in its declaration
1126 file; one that declares none is taken at the current version.
1127 """
1128 declared = found.api_version
1129 if declared != API_VERSION:
1130 raise RuntimeError(
1131 f"extension {extension!r} declares workshop API version {declared!r}; this"
1132 f" workshop is version {API_VERSION}. Install a release of the"
1133 " extension written for this workshop, or of the workshop the extension"
1134 " was written for."
1135 )
1136
1137
1138def extension_dependencies(start: Path | None = None) -> dict[str, tuple[str, ...]]:(empty)
1139 """Each listed extension's ``[extension] requires``, name to names.
1140
1141 The base declares none here, and an extension no installed
1142 distribution declares has none to read: the mount teaches the
1143 install.
1144 """
1145 found: dict[str, tuple[str, ...]] = {}
1146 for extension in extension_names(start):
1147 declared = _readable(extension)
1148 found[extension] = declared.requires if declared is not None else ()
1149 return found
1150
1151
1152def extension_tools(start: Path | None = None) -> dict[str, tuple[str, ...]]:(empty)
1153 """Each listed extension's ``[toolroom] requires``, name to requirement strings.
1154
1155 The tools the extension runs, such as cmake's ``cmake`` and
1156 ``ninja`` or a verb's ``docker>=27``, then the tools each of its
1157 ``[for.<target>]`` tables requires while the table applies, as
1158 [livery.workshop.contributions_for][] decides it: a measurer's tool
1159 is required while the workspace lists what it measures for, and
1160 never otherwise. An extension no installed distribution declares
1161 declares none here, and the base declares its own in its contract
1162 file, which the tool requirements read at a site of its own.
1163 """
1164 active = resolved_targets(start)
1165 applies = _contributing(active)
1166 found: dict[str, tuple[str, ...]] = {}
1167 for extension in active:
1168 declared = _readable(extension)
1169 if declared is None:1169 ↛ 1170line 1169 didn't jump to line 1170 because the condition on line 1169 was never true
1170 found[extension] = ()
1171 continue
1172 found[extension] = (
1173 *declared.tools,
1174 *(
1175 text
1176 for target in applies.get(extension, ())
1177 for text in declared.target_tools.get(target, ())
1178 ),
1179 )
1180 return found
1181
1182
1183def notes_tools(start: Path | None = None) -> dict[str, tuple[str, ...]]:(empty)
1184 """Each listed extension that writes release notes, to its ``[toolroom] requires``.
1185
1186 A release's entries must not depend on the machine that wrote
1187 them, so no host allowance reaches these tools
1188 ([livery.workshop._tools.host_allowed][]).
1189 """
1190 from livery.workshop._release_notes import RELEASE_NOTES
1191
1192 found: dict[str, tuple[str, ...]] = {}
1193 for extension in extension_names(start):
1194 declared = _readable(extension)
1195 if declared is not None and RELEASE_NOTES.name in declared.queries:1195 ↛ 1196line 1195 didn't jump to line 1196 because the condition on line 1195 was never true
1196 found[extension] = declared.tools
1197 return found
1198
1199
1200def declared_targets(start: Path | None = None) -> dict[str, dict[str, Additions]]:(empty)
1201 """Each listed extension's ``[for.<target>]`` tables, owner to target to tables."""
1202 found: dict[str, dict[str, Additions]] = {}
1203 for extension in extension_names(start):
1204 declared = _readable(extension)
1205 found[extension] = dict(declared.targets) if declared is not None else {}
1206 return found
1207
1208
1209def resolved_targets(start: Path | None = None) -> dict[str, tuple[str, ...]]:(empty)
1210 """Each extension of the installed set to its active targets, in composition order.
1211
1212 Every target of the installed set the extension declares a
1213 ``[for.<target>]`` table for, except those its root entry's
1214 ``without`` names: cooperation is greedy, and an opt-out names what
1215 is off (``left_out``).
1216 """
1217 names = extension_names(start)
1218 declared = declared_targets(start)
1219 off = left_out(start)
1220 return {
1221 owner: tuple(
1222 name
1223 for name in names
1224 if name in declared.get(owner, {}) and name not in off.get(owner, ())
1225 )
1226 for owner in names
1227 }
1228
1229
1230def contributions_for((empty)
1231 target: str, start: Path | None = None
1232) -> dict[str, dict[str, Any]]:
1233 """What the installed extensions declare for *target*, by extension.
1234
1235 The extensions come in composition order. An extension contributes
1236 its ``[for.<target>]`` table while *target* is listed and the
1237 extension's listing contributes to it (every listed target it
1238 declares a table for, except those its root entry's ``without``
1239 names), the rule the mount grafts by; an extension that requires
1240 *target* contributes its top-level tables. The tables come as the
1241 declaration file holds them, and an extension that declares nothing
1242 for *target* is left out, as is every extension when *target* is
1243 not listed. *start* is a directory in the workspace, the working
1244 directory when absent.
1245 """
1246 names = extension_names(start)
1247 if target not in names:
1248 return {}
1249 contributes = contributing(start)
1250 found: dict[str, dict[str, Any]] = {}
1251 for owner in names:
1252 declared = _readable(owner)
1253 if declared is None or owner == target:
1254 continue
1255 if target in declared.requires:
1256 found[owner] = dict(declared.tables)
1257 elif target in contributes.get(owner, ()):
1258 found[owner] = dict(declared.target_tables[target])
1259 return found
1260
1261
1262def contributing(start: Path | None = None) -> dict[str, tuple[str, ...]]:(empty)
1263 """Each listed extension to the listed targets its ``[for]`` tables apply to now.
1264
1265 A target is listed, the owner declares a ``[for.<target>]`` table for
1266 it, and the owner's root entry does not name it in ``without``. An
1267 extension that contributes to nothing is left out. The rule the
1268 mount grafts by, which [livery.workshop.contributions_for][], the
1269 delivery of a table's files and dormancy read through.
1270 """
1271 return _contributing(resolved_targets(start))
1272
1273
1274def _contributing(active: dict[str, tuple[str, ...]]) -> dict[str, tuple[str, ...]]:(empty)
1275 """What `contributing` answers, from *active*: each listed extension's targets.
1276
1277 *active* is [livery.workshop._extensions.resolved_targets][]'s
1278 answer, which holds every extension of the installed set, in
1279 composition order, so a caller that already has it reads no
1280 contract again.
1281 """
1282 found: dict[str, tuple[str, ...]] = {}
1283 for owner, resolved in active.items():
1284 declared = _readable(owner)
1285 if declared is None:
1286 continue
1287 targets = tuple(
1288 target
1289 for target in resolved
1290 if target != owner and target in active and target in declared.target_tables
1291 )
1292 if targets:
1293 found[owner] = targets
1294 return found
1295
1296
1297def dormancy(start: Path | None = None) -> dict[str, str]:(empty)
1298 """Each listed extension that is dormant now, to what it waits for.
1299
1300 An extension whose ``[extension] dormant-until`` names what another
1301 does for it, ``measures`` for coverage, is dormant while no listed
1302 extension contributes a ``[for.<it>]`` table to it
1303 ([livery.workshop._extensions.contributing][]): it registers no step
1304 and no job, and its plugin still mounts. The text says what it waits
1305 for and names the installed extensions whose declarations carry such
1306 a table, which would wake it: ``nothing listed measures; cmake and
1307 pytest would``. A listing kept for a contributor still to come is a
1308 statement of intent, so dormancy is named, never refused.
1309 """
1310 active = resolved_targets(start)
1311 return _dormant(tuple(active), _contributing(active))
1312
1313
1314def _dormant((empty)
1315 names: tuple[str, ...], contributes: dict[str, tuple[str, ...]]
1316) -> dict[str, str]:
1317 """`dormancy` over the listed *names*, given what each contributes to."""
1318 woken = {target for targets in contributes.values() for target in targets}
1319 found: dict[str, str] = {}
1320 for name in names:
1321 declared = _readable(name)
1322 if declared is None or not declared.dormant_until or name in woken:
1323 continue
1324 wakers = _wakers(name)
1325 would = f"{_spoken(wakers)} would" if wakers else "no installed extension would"
1326 found[name] = f"nothing listed {declared.dormant_until}; {would}"
1327 return found
1328
1329
1330def _wakers(target: str) -> list[str]:(empty)
1331 """The installed extensions whose declarations carry a ``[for.<target>]`` table.
1332
1333 Sorted. An installed declaration that cannot be read is left out:
1334 an extension the workspace does not list is not its to judge.
1335 """
1336 found: list[str] = []
1337 for name in installed_extensions():
1338 if name == target:
1339 continue
1340 try:
1341 declared = _readable(name)
1342 except DeclarationError:
1343 continue
1344 if declared is not None and target in declared.target_tables:
1345 found.append(name)
1346 return found
1347
1348
1349def _spoken(names: list[str]) -> str:(empty)
1350 """*names* as a sentence lists them: ``a``, ``a and b``, ``a, b and c``."""
1351 if len(names) < 2:
1352 return "".join(names)
1353 return f"{', '.join(names[:-1])} and {names[-1]}"
1354
1355
1356def describe_extensions(start: Path | None = None) -> list[str]:(empty)
1357 """The lines ``fm extensions`` prints: each extension with what it declares.
1358
1359 The base, then each extension of the installed set in mount order;
1360 under each, who requires it, the packages whose sets hold it, its
1361 tools, the targets it contributes to, the targets its root entry
1362 leaves out, whether it is dormant and what would wake it, and the
1363 steps it declares off, each with whether it is on.
1364 """
1365 names = extension_names(start)
1366 who = requirers(start)
1367 tools = extension_tools(start)
1368 targets = resolved_targets(start)
1369 off = left_out(start)
1370 enabled = enabled_steps(start)
1371 holders = _holders(start)
1372 asleep = dormancy(start)
1373 lines: list[str] = [f" {SELF} (the base)"]
1374 for name in names:
1375 needed = who.get(name, ())
1376 by = f" (required by {', '.join(needed)})" if needed else ""
1377 lines.append(f" {name}{by}")
1378 if holders.get(name):
1379 lines.append(f" packages: {', '.join(holders[name])}")
1380 if tools.get(name):
1381 lines.append(f" tools: {', '.join(tools[name])}")
1382 if targets.get(name):
1383 lines.append(f" for: {', '.join(targets[name])}")
1384 if off.get(name):
1385 lines.append(f" without: {', '.join(off[name])}")
1386 if name in asleep:
1387 lines.append(f" dormant: {asleep[name]}")
1388 for step in _declared_off(name):
1389 state = "on" if step in enabled else "off"
1390 phase, _, name_in_phase = step.partition(".")
1391 lines.append(
1392 f" step {step} ({state}): declared off; the root contract turns"
1393 f" it on with [phases.{phase}.{name_in_phase}] enabled = true"
1394 )
1395 return lines
1396
1397
1398def _declared_off(extension: str) -> tuple[str, ...]:(empty)
1399 """The steps *extension* declares ``enabled = false``, each ``<phase>.<step>``.
1400
1401 Those of its top-level tables and of its ``[for.<target>]`` tables
1402 alike, in the file's order; empty for the base and for an extension
1403 nothing installed declares.
1404 """
1405 found = _readable(extension)
1406 if found is None:
1407 return ()
1408 steps = [*found.additions.steps]
1409 for additions in found.targets.values():
1410 steps += additions.steps
1411 return tuple(record.name for record in steps if not record.enabled)
1412
1413
1414def enabled_problems(root: Path) -> list[str]:(empty)
1415 """Each root ``[phases.<phase>.<step>]`` table turning on no step declared off.
1416
1417 The root contract turns on a step a listed extension declares
1418 ``enabled = false``; a table naming any other step, one no listed
1419 extension declares or one that is on already, is refused naming
1420 the steps declared off.
1421 """
1422 off = {step: name for name in extension_names(root) for step in _declared_off(name)}
1423 problems: list[str] = []
1424 for step in sorted(enabled_steps(root)):
1425 if step in off:
1426 continue
1427 phase, _, name = step.partition(".")
1428 declared = ", ".join(f"{other} ({by})" for other, by in sorted(off.items()))
1429 problems.append(
1430 f"[phases.{phase}.{name}] turns on {step}, which no listed extension"
1431 " declares off; the steps declared off are"
1432 f" {declared or 'none'}"
1433 )
1434 return problems
1435
1436
1437def _holders(start: Path | None) -> dict[str, tuple[str, ...]]:(empty)
1438 """Each extension a package's set holds to the packages holding it, by path."""
1439 root = workspace_root(start)
1440 if root is None:
1441 return {}
1442 found: dict[str, list[str]] = {}
1443 for contract, listed in _package_lists(root):
1444 where = contract.parent.relative_to(root).as_posix()
1445 names = [listing(entry).name for entry in listed]
1446 for name in closure(names, installed_declaration):
1447 found.setdefault(name, []).append(where)
1448 return {name: tuple(where) for name, where in found.items()}
1449
1450
1451def closure_problems(start: Path | None = None) -> list[str]:(empty)
1452 """Why the contracts' lists are not valid compositions in their canonical form.
1453
1454 Empty when every target a root entry's ``without`` names is in the
1455 installed set and its extension declares a contribution for it;
1456 when every listed extension is installed and every entry is a name
1457 alone (``entry_problems``); when every step the root contract turns
1458 on is one a listed extension declares off (``enabled_problems``);
1459 when the root's list is its canonical one (``root_list_problems``);
1460 and when every package's list is a valid composition in its
1461 canonical form, each of its entries composing something in a
1462 package (``composition_problems``). The gate's ``--fix`` writes
1463 each list in its canonical form and moves a package's entry that
1464 composes nothing to the root's list (``write_extensions``).
1465 """
1466 root = workspace_root(start)
1467 installed = set(installed_set(start))
1468 problems: list[str] = []
1469 declared = declared_targets(start)
1470 for owner, targets in left_out(start).items():
1471 if installed_declaration(owner) is None:
1472 # entry_problems names an extension nothing installed declares.
1473 continue
1474 for target in targets:
1475 if target not in declared.get(owner, {}):
1476 problems.append(
1477 f"[workspace] extensions: the entry for {owner} names {target}"
1478 f" in `without`, and {owner} declares no contribution for it;"
1479 " remove it from `without`"
1480 )
1481 elif target not in installed:
1482 problems.append(
1483 f"[workspace] extensions: the entry for {owner} names {target}"
1484 " in `without`, and the installed set does not hold it; list"
1485 " it, or remove it from `without`"
1486 )
1487 if root is not None:
1488 if why := missing_list(root):
1489 problems.append(why)
1490 problems += entry_problems(root)
1491 problems += listing_problems(root)
1492 problems += enabled_problems(root)
1493 problems += root_list_problems(root)
1494 problems += composition_problems(root)
1495 return problems
1496
1497
1498#: An entry of the root's list as the contract holds it: a name, or a
1499#: table of the name and the targets it leaves out.
1500Entry = str | dict[str, Any](empty)
1501
1502
1503@dataclass(frozen=True)(empty)
1504class _RootList:(empty)
1505 """The root's ``[workspace] extensions`` as written, and its canonical form.
1506
1507 Attributes:
1508 written: Each entry as the contract holds it, in the written order.
1509 wanted: Each entry of the canonical list, with the index of the
1510 written entry it comes from.
1511 why: Why the two differ, after a semicolon; empty when they agree.
1512 """
1513
1514 written: tuple[Entry, ...](empty)
1515 wanted: tuple[tuple[int, Entry], ...](empty)
1516 why: str(empty)
1517
1518
1519def _root_list(root: Path) -> _RootList | str | None:(empty)
1520 """The root's list and its canonical form; a cycle's refusal; None when not judged.
1521
1522 Judged once every entry is the name of an installed extension, or a
1523 table of that name and ``without``: the other problems name any
1524 other entry first. The canonical list holds each extension of the
1525 root's set once, in composition order. It leaves out an entry
1526 another listed extension requires, unless the entry carries a
1527 ``without``: an implied extension's opt-out has no other place to
1528 be written. A table entry whose ``without`` is empty or absent is
1529 written as the name alone.
1530 """
1531 from livery.workshop._composition import implied, order
1532
1533 written: tuple[Entry, ...] = tuple(_listed(root))
1534 names: list[str] = []
1535 for entry in written:
1536 name = _spelling(entry)
1537 if isinstance(entry, dict) and not _judged_table(entry):
1538 return None
1539 if listing(name).name != name or installed_declaration(name) is None:
1540 return None
1541 names.append(name)
1542 members = closure(names, installed_declaration)
1543 try:
1544 ordered = order(members, installed_declaration)
1545 except OrderCycle as error:
1546 return f"[workspace] extensions: {error}"
1547 required = implied(members, installed_declaration)
1548
1549 def canonical(name: str, entry: Entry) -> Entry:
1550 return entry if isinstance(entry, dict) and entry.get("without") else name
1551
1552 chosen: dict[str, tuple[int, Entry]] = {}
1553 for index, (name, entry) in enumerate(zip(names, written, strict=True)):
1554 wanted = canonical(name, entry)
1555 held = chosen.get(name)
1556 if held is None or (isinstance(wanted, dict) and isinstance(held[1], str)):
1557 chosen[name] = (index, wanted)
1558 kept = tuple(
1559 chosen[name]
1560 for name in ordered
1561 if name in chosen
1562 and (name not in required or isinstance(chosen[name][1], dict))
1563 )
1564 if [entry for _index, entry in kept] == list(written):
1565 return _RootList(written, kept, "")
1566 gone = [name for name in chosen if name not in {_spelling(e) for _i, e in kept}]
1567 plain = [
1568 _spelling(written[index])
1569 for index, entry in kept
1570 if isinstance(entry, str) and isinstance(written[index], dict)
1571 ]
1572 if gone:
1573 verb = "is" if len(gone) == 1 else "are"
1574 why = f"; {', '.join(gone)} {verb} required by another listed extension"
1575 elif len(plain) == 1:
1576 why = (
1577 f"; the entry for {plain[0]} leaves out no target, which the name"
1578 " alone says"
1579 )
1580 elif plain:1580 ↛ 1581line 1580 didn't jump to line 1581 because the condition on line 1580 was never true
1581 why = (
1582 f"; the entries for {' and '.join(plain)} leave out no target,"
1583 " which a name alone says"
1584 )
1585 elif len(chosen) != len(names):
1586 why = "; it lists an extension twice"
1587 else:
1588 why = (
1589 "; its order is composition order: each extension after what it"
1590 " requires, ties alphabetical"
1591 )
1592 return _RootList(written, kept, why)
1593
1594
1595def _judged_table(entry: dict[str, Any]) -> bool:(empty)
1596 """Whether the root's table entry *entry* is a name and a ``without`` of names.
1597
1598 Any other table is the contract judge's to name, and the list is
1599 judged canonical once it is gone.
1600 """
1601 targets = entry.get("without", [])
1602 return (
1603 set(entry) <= {"name", "without"}
1604 and isinstance(targets, list)
1605 and all(isinstance(target, str) for target in cast("list[object]", targets))
1606 )
1607
1608
1609def _spelled_entries(entries: Iterable[Entry]) -> str:(empty)
1610 """*entries* as a contract spells the root's list."""
1611 spelled: list[str] = []
1612 for entry in entries:
1613 if isinstance(entry, str):
1614 spelled.append(f'"{entry}"')
1615 continue
1616 parts = [f'name = "{_spelling(entry)}"']
1617 if "without" in entry:
1618 targets = ", ".join(f'"{target}"' for target in entry["without"])
1619 parts.append(f"without = [{targets}]")
1620 spelled.append("{ " + ", ".join(parts) + " }")
1621 return "[" + ", ".join(spelled) + "]"
1622
1623
1624def root_list_problems(root: Path) -> list[str]:(empty)
1625 """Why ``[workspace] extensions`` is not its canonical list; empty when it is.
1626
1627 The canonical list holds each extension once, in composition order.
1628 It leaves out an entry another listed extension requires unless the
1629 entry carries a ``without``, and writes a table entry whose
1630 ``without`` is empty or absent as the name alone. No other order
1631 means anything, so the list is written in this one, which the
1632 gate's ``--fix`` writes. A list whose set's declared order has no
1633 start names the cycle. An entry that is not an installed
1634 extension's name is named by ``entry_problems`` and
1635 ``listing_problems``, and the list is judged once they pass.
1636 """
1637 found = _root_list(root)
1638 if found is None:
1639 return []
1640 if isinstance(found, str):1640 ↛ 1641line 1640 didn't jump to line 1641 because the condition on line 1640 was never true
1641 return [found]
1642 if not found.why:
1643 return []
1644 wanted = (entry for _index, entry in found.wanted)
1645 return [
1646 f"[workspace] extensions is {_spelled_entries(found.written)}, and its"
1647 f" canonical list is {_spelled_entries(wanted)}{found.why}; the gate's"
1648 " --fix rewrites it"
1649 ]
1650
1651
1652def _composable(listed: tuple[str, ...]) -> bool:(empty)
1653 """Whether every entry of a package's list is a name something installed declares.
1654
1655 A package whose list holds anything else is
1656 [livery.workshop._extensions.entry_problems][]'s to name, and its
1657 composition is judged once that is fixed.
1658 """
1659 return all(
1660 listing(entry).name == entry and installed_declaration(entry) is not None
1661 for entry in listed
1662 )
1663
1664
1665def _spelled(names: tuple[str, ...] | list[str]) -> str:(empty)
1666 """*names* as a contract spells the list."""
1667 return "[" + ", ".join(f'"{name}"' for name in names) + "]"
1668
1669
1670def composition_problems(root: Path) -> list[str]:(empty)
1671 """Why each package's list is not a valid composition in its canonical form.
1672
1673 Judged for each package whose entries are names installed
1674 distributions declare: every extension its set requires is
1675 installed, each lifecycle phase can run as the set's extensions
1676 declare it ([livery.workshop._phases.phase_problems][]), each entry
1677 no other entry requires composes something in a package, itself or
1678 through what it requires (`why_inert`), the set's declared order
1679 has a start, and the list is the canonical one
1680 ([livery.workshop._composition.canonical][]). The gate's ``--fix``
1681 writes the canonical list and moves an entry that composes nothing
1682 to ``[workspace] extensions`` (`write_extensions`). A requirement
1683 joins the set whatever it declares, so no other list needs to name
1684 it. A cycle of requirements shows in every package whose set holds
1685 one of its members, since a set is closed under requires.
1686 """
1687 from livery.workshop._composition import canonical, implied
1688 from livery.workshop._phases import lifecycle_phases, phase_problems, phase_steps
1689
1690 problems: list[str] = []
1691 inert: dict[str, str] = {}
1692 for contract, listed in _package_lists(root):
1693 if not _composable(listed):
1694 continue
1695 where = contract.parent.relative_to(root).as_posix()
1696 names = list(listed)
1697 members = closure(names, installed_declaration)
1698 for name in members:
1699 found = installed_declaration(name)
1700 for needed in found.requires if found is not None else ():
1701 if installed_declaration(needed) is None:
1702 problems.append(
1703 f"{where}: {name} requires {needed}, which no installed"
1704 f" distribution declares in {GROUP}; install it"
1705 )
1706 for phase in lifecycle_phases():
1707 steps = phase_steps(phase, members, installed_declaration)
1708 problems += [f"{where}: {line}" for line in phase_problems(phase, steps)]
1709 required = implied(members, installed_declaration)
1710 for name in dict.fromkeys(names):
1711 if name in required:
1712 continue
1713 if name not in inert:
1714 inert[name] = why_inert(name)
1715 if inert[name]:
1716 problems.append(
1717 f"{where}: `extensions` lists {name}, which composes nothing in a"
1718 f" package: {inert[name]}; list it in [workspace] extensions,"
1719 " where the gate's --fix moves it"
1720 )
1721 try:
1722 wanted = canonical(names, installed_declaration)
1723 except OrderCycle as error:
1724 problems.append(f"{where}: {error}")
1725 continue
1726 if tuple(names) != wanted:
1727 problems.append(
1728 f"{where}: `extensions` is {_spelled(names)}, and its canonical list"
1729 f" is {_spelled(wanted)}{_why(names, wanted)}; the gate's --fix"
1730 " rewrites it"
1731 )
1732 return problems
1733
1734
1735def _why(names: list[str], wanted: tuple[str, ...]) -> str:(empty)
1736 """Why a package's list differs from its canonical one, after a semicolon."""
1737 implied = [name for name in dict.fromkeys(names) if name not in wanted]
1738 if implied:
1739 verb = "is" if len(implied) == 1 else "are"
1740 return f"; {', '.join(implied)} {verb} required by another listed extension"
1741 if len(set(names)) != len(names):
1742 return "; it lists an extension twice"
1743 return (
1744 "; its order is composition order: each extension after what it requires,"
1745 " ties alphabetical"
1746 )
1747
1748
1749def listing_problems(root: Path) -> list[str]:(empty)
1750 """Each ``[workspace] extensions`` entry spelled as more than a name.
1751
1752 An entry is a name. It takes no brackets, version, ``?`` or scope:
1753 an extension's version comes from its wheel's metadata, and the
1754 lock pins it. An extension no installed distribution declares is
1755 [livery.workshop._extensions.entry_problems][]'s to name.
1756 """
1757 from livery.toolroom.store import Spec, SpecError
1758
1759 problems: list[str] = []
1760 for entry in _listed(root):
1761 spelled = _spelling(entry)
1762 try:
1763 spec = Spec.parse(spelled, where="[workspace] extensions")
1764 except SpecError:
1765 spec = None
1766 if spec is None or spec.options or spec.optional or spec.floor or spec.scope:
1767 problems.append(
1768 f"[workspace] extensions lists {spelled!r}; an entry is a name alone,"
1769 " with no brackets, version or scope: the lock pins an extension's"
1770 " version from its wheel"
1771 )
1772 return problems
1773
1774
1775_LISTS: dict[tuple[Path, str], tuple[str, ...]] = {}(empty)
1776
1777
1778def _package_lists(root: Path) -> list[tuple[Path, tuple[str, ...]]]:(empty)
1779 """Each package contract under *root* with the extensions it lists.
1780
1781 Read raw, as the root's list is, since the mount reads it before any
1782 verb judges a contract. A contract that is not TOML, or whose
1783 ``extensions`` is no list, lists nothing here: the judge names it
1784 when the package is read, and every command, ``fm sync`` among
1785 them, still mounts. Each contract is parsed once per content: every
1786 command's mount asks, and a package's list changes only when its
1787 text does.
1788 """
1789 from livery.workshop._packages import package_directories
1790
1791 found: list[tuple[Path, tuple[str, ...]]] = []
1792 for directory in package_directories(root):
1793 contract = directory / "workshop.toml"
1794 if not contract.is_file():
1795 continue
1796 text = contract.read_text("utf-8")
1797 listed = _LISTS.get((contract, text))
1798 if listed is None:
1799 try:
1800 table = tomllib.loads(text)
1801 except tomllib.TOMLDecodeError:
1802 table = {}
1803 entries = table.get("extensions", [])
1804 listed = (
1805 tuple(str(name) for name in entries)
1806 if isinstance(entries, list)
1807 else ()
1808 )
1809 _LISTS[(contract, text)] = listed
1810 found.append((contract, listed))
1811 return found
1812
1813
1814def entry_problems(root: Path) -> list[str]:(empty)
1815 """Each listed name nothing installed declares, and each package entry with options.
1816
1817 Every extension is one kind, which either list names. A package's
1818 entry is the extension's name alone, with no options.
1819 """
1820 problems: list[str] = []
1821 for name in workspace_names(root):
1822 if declaration(name) is None:
1823 problems.append(
1824 f"[workspace] extensions lists {name}, which no installed"
1825 f" distribution declares in {GROUP}"
1826 )
1827 for contract, listed in _package_lists(root):
1828 where = contract.parent.relative_to(root).as_posix()
1829 for name in listed:
1830 if listing(name).name != name:
1831 problems.append(
1832 f"{where}: `extensions` lists {name!r}; a package's entry is the"
1833 " extension's name alone, and takes no options"
1834 )
1835 continue
1836 if declaration(name) is None:
1837 problems.append(
1838 f"{where}: `extensions` lists {name}, which no installed"
1839 f" distribution declares in {GROUP}"
1840 )
1841 return problems
1842
1843
1844def requirers(start: Path | None = None) -> dict[str, tuple[str, ...]]:(empty)
1845 """Each listed extension to the listed extensions that depend on it."""
1846 found: dict[str, list[str]] = {name: [] for name in extension_names(start)}
1847 for extension, depends in extension_dependencies(start).items():
1848 for needed in depends:
1849 found.setdefault(needed, []).append(extension)
1850 return {name: tuple(who) for name, who in found.items()}
1851
1852
1853def write_extensions(root: Path) -> list[str]:(empty)
1854 """Write each package's list and the root's in its canonical form.
1855
1856 Returns the lines written, one per list changed.
1857
1858 Each package's list becomes its canonical one
1859 ([livery.workshop._composition.canonical][]) without the entries
1860 that compose nothing in a package (`why_inert`), which move to the
1861 root's list, and the root's list then becomes its canonical one
1862 (``root_list_problems``). Each entry keeps the comment lines above
1863 it and the comment after it on its line. A moved entry takes them
1864 to the root's list when that list does not hold it yet, and an
1865 entry left out takes its comments with it. A list the judge refuses
1866 for another reason, one whose order has no start, and one whose
1867 array this does not read are left for a person, and the judge names
1868 each; no entry moves while the root's array is not read.
1869 Idempotent. A root without a contract lists no extensions, so
1870 nothing is written.
1871 """
1872 from livery.workshop._composition import canonical
1873
1874 contract = root / "workshop.toml"
1875 if not contract.is_file():
1876 return []
1877 movable = _read_array(contract.read_text(encoding="utf-8"), "workspace") is not None
1878 moved: dict[str, _Entry] = {}
1879 inert: dict[str, str] = {}
1880 written: list[str] = []
1881 for package_contract, listed in _package_lists(root):
1882 if not _composable(listed):
1883 continue
1884 where = package_contract.parent.relative_to(root).as_posix()
1885 try:
1886 wanted = canonical(listed, installed_declaration)
1887 except OrderCycle:
1888 continue
1889 leaving: list[str] = []
1890 for name in wanted if movable else ():
1891 if name not in inert:
1892 inert[name] = why_inert(name)
1893 if inert[name]:
1894 leaving.append(name)
1895 kept = tuple(name for name in wanted if name not in leaving)
1896 if kept == listed:
1897 continue
1898 package_text = package_contract.read_text(encoding="utf-8")
1899 array = _read_array(package_text, None)
1900 if array is None or not _reads_as(array, listed):
1901 continue
1902 # The canonical list holds each extension once, each one listed.
1903 entries = [array.entries[listed.index(name)] for name in kept]
1904 package_contract.write_text(
1905 package_text[: array.start]
1906 + _array_text(array, entries)
1907 + package_text[array.end :],
1908 encoding="utf-8",
1909 )
1910 for name in leaving:
1911 moved.setdefault(name, array.entries[listed.index(name)])
1912 if leaving:
1913 verb = "composes" if len(leaving) == 1 else "compose"
1914 written.append(
1915 f" layering: {where} `extensions` is {_spelled(kept)}, and"
1916 f" [workspace] extensions lists {_spoken(leaving)}, which {verb}"
1917 " nothing in a package"
1918 )
1919 else:
1920 written.append(
1921 f" layering: {where} `extensions` is {_spelled(kept)},"
1922 " its canonical list"
1923 )
1924 return _write_root(root, moved) + written
1925
1926
1927def _write_root(root: Path, moved: dict[str, _Entry]) -> list[str]:(empty)
1928 """Add *moved* to the root's list, then write it in its canonical form.
1929
1930 *moved* maps each extension a package's list gave up to its entry
1931 there, with its comments; an extension the root's list holds
1932 already is not added again. Returns the line written for the
1933 canonical rewrite, if any: the line of each package's list names
1934 what moved.
1935 """
1936 contract = root / "workshop.toml"
1937 text = contract.read_text(encoding="utf-8")
1938 held = set(workspace_names(root))
1939 added = [entry for name, entry in moved.items() if name not in held]
1940 array = _read_array(text, "workspace")
1941 if added and array is not None:
1942 text = (
1943 text[: array.start]
1944 + _array_text(array, [*array.entries, *added])
1945 + text[array.end :]
1946 )
1947 contract.write_text(text, encoding="utf-8")
1948 found = _root_list(root)
1949 if not isinstance(found, _RootList) or not found.why:
1950 return []
1951 array = _read_array(text, "workspace")
1952 if array is None or not _reads_as(array, found.written):
1953 return []
1954 entries = [
1955 replace(array.entries[index], text=f'"{entry}"')
1956 if isinstance(entry, str) and isinstance(found.written[index], dict)
1957 else array.entries[index]
1958 for index, entry in found.wanted
1959 ]
1960 contract.write_text(
1961 text[: array.start] + _array_text(array, entries) + text[array.end :],
1962 encoding="utf-8",
1963 )
1964 spelled = _spelled_entries(entry for _index, entry in found.wanted)
1965 return [f" layering: [workspace] extensions is {spelled}, its canonical list"]
1966
1967
1968def list_in_root(root: Path, names: Iterable[str]) -> list[str]:(empty)
1969 """Add *names* to *root*'s ``[workspace] extensions``, as its canonical list.
1970
1971 Each name the list does not hold yet joins it as an entry of its
1972 own, and the list is then written in its canonical form, as the
1973 gate's ``--fix`` writes it (`write_extensions`): each entry keeps
1974 its comments, and an entry another listed extension requires
1975 leaves the list. A list naming an extension no installed
1976 distribution declares keeps the order it is given, and the gate
1977 names it. Returns what `write_extensions` returns: a line for each
1978 list it wrote.
1979
1980 Raises:
1981 Failed: when the contract has no ``[workspace] extensions``
1982 array this reads.
1983 """
1984 from livery.footman import fail
1985
1986 contract = root / "workshop.toml"
1987 text = contract.read_text(encoding="utf-8")
1988 array = _read_array(text, "workspace")
1989 if array is None:
1990 fail(f"{contract}: no [workspace] extensions array to add to")
1991 held = set(workspace_names(root))
1992 added = [_Entry(f'"{name}"') for name in dict.fromkeys(names) if name not in held]
1993 if added:
1994 contract.write_text(
1995 text[: array.start]
1996 + _array_text(array, [*array.entries, *added])
1997 + text[array.end :],
1998 encoding="utf-8",
1999 )
2000 return write_extensions(root)
2001
2002
2003@dataclass(frozen=True)(empty)
2004class _Entry:(empty)
2005 """One entry of an ``extensions`` array as written, with its comments.
2006
2007 Attributes:
2008 text: The entry itself, ``"ruff"`` or
2009 ``{ name = "pytest", without = ["coverage"] }``.
2010 above: The whole lines between the entry before it and this one,
2011 its comment lines and blank lines, as written.
2012 after: The comment after the entry on its own line; empty without one.
2013 """
2014
2015 text: str(empty)
2016 above: tuple[str, ...] = ()(empty)
2017 after: str = ""(empty)
2018
2019
2020@dataclass(frozen=True)(empty)
2021class _Array:(empty)
2022 """An ``extensions`` array as a contract writes it, read for a rewrite.
2023
2024 Attributes:
2025 start: Where the key's line starts in the contract's text.
2026 end: Where the array ends, after its closing bracket.
2027 key: The text from the line's start to the opening bracket.
2028 head: The comment after the opening bracket on its line; empty
2029 without one.
2030 entries: The entries, in the written order.
2031 tail: The whole lines after the last entry, before the closing
2032 bracket.
2033 indent: What stands before an entry on a line of its own.
2034 multiline: Whether the array spans more than one line.
2035 """
2036
2037 start: int(empty)
2038 end: int(empty)
2039 key: str(empty)
2040 head: str(empty)
2041 entries: tuple[_Entry, ...](empty)
2042 tail: tuple[str, ...](empty)
2043 indent: str(empty)
2044 multiline: bool(empty)
2045
2046
2047#: A table header: the line's first character after its indent is ``[``.
2048_HEADER = re.compile(r"^[ \t]*\[", re.M)(empty)
2049
2050#: The ``extensions`` key, up to its array's opening bracket.
2051_KEY = re.compile(r"^[ \t]*extensions[ \t]*=[ \t]*\[", re.M)(empty)
2052
2053
2054def _region(text: str, table: str | None) -> tuple[int, int] | None:(empty)
2055 """Where *table*'s keys stand in *text*; the top level's for None.
2056
2057 None when *text* has no header for *table*.
2058 """
2059 if table is None:
2060 header = _HEADER.search(text)
2061 return 0, header.start() if header is not None else len(text)
2062 found = re.compile(
2063 rf"^[ \t]*\[[ \t]*{re.escape(table)}[ \t]*\][ \t]*(?:#.*)?$", re.M
2064 ).search(text)
2065 if found is None:
2066 return None
2067 after = _HEADER.search(text, found.end())
2068 return found.end(), after.start() if after is not None else len(text)
2069
2070
2071def _read_array(text: str, table: str | None) -> _Array | None:(empty)
2072 """The ``extensions`` array of *table* in *text*, as written; None when not read.
2073
2074 *table* is ``workspace`` for the root's list and None for a
2075 package's, which stands at the top level. An entry is a string or
2076 an inline table; an array holding anything else, a multi-line
2077 string among them, is not read, and neither is a key spelled
2078 otherwise.
2079 """
2080 region = _region(text, table)
2081 if region is None:
2082 return None
2083 key = _KEY.search(text, *region)
2084 if key is None:2084 ↛ 2085line 2084 didn't jump to line 2085 because the condition on line 2084 was never true
2085 return None
2086 entries: list[_Entry] = []
2087 pending: list[str] = []
2088 head = ""
2089 indent = ""
2090 line = key.start()
2091 # Whether the line read holds the opening bracket, holds an entry or
2092 # a comma, and holds nothing but space so far.
2093 first, taken, blank = True, False, True
2094 at = key.end()
2095 while at < len(text):2095 ↛ 2139line 2095 didn't jump to line 2139 because the condition on line 2095 was always true
2096 char = text[at]
2097 if char in " \t\r":
2098 at += 1
2099 elif char == "\n":
2100 if blank and not first:
2101 pending.append("")
2102 at += 1
2103 line, first, taken, blank = at, False, False, True
2104 elif char == "]":
2105 return _Array(
2106 key.start(),
2107 at + 1,
2108 key.group(0),
2109 head,
2110 tuple(entries),
2111 tuple(pending),
2112 indent or " ",
2113 "\n" in text[key.end() : at],
2114 )
2115 elif char == "#":
2116 stop = text.find("\n", at)
2117 stop = len(text) if stop < 0 else stop
2118 if taken and entries:
2119 entries[-1] = replace(entries[-1], after=text[at:stop].rstrip())
2120 elif first:
2121 head = text[at:stop].rstrip()
2122 else:
2123 pending.append(text[line:stop].rstrip())
2124 blank = False
2125 at = stop
2126 elif char == ",":
2127 taken, blank = True, False
2128 at += 1
2129 else:
2130 end = _item_end(text, at)
2131 if end is None:
2132 return None
2133 if not taken and not first and not indent:
2134 indent = text[line:at]
2135 entries.append(_Entry(text[at:end], tuple(pending)))
2136 pending = []
2137 taken, blank = True, False
2138 at = end
2139 return None
2140
2141
2142def _item_end(text: str, at: int) -> int | None:(empty)
2143 """Where the string or inline table at *at* ends; None for anything else.
2144
2145 A multi-line string is not read. The text parses as TOML already,
2146 so every string and table here closes.
2147 """
2148 char = text[at]
2149 if char in "\"'":
2150 if text.startswith(char * 3, at):
2151 return None
2152 index = at + 1
2153 while index < len(text) and text[index] != char:
2154 index += 2 if char == '"' and text[index] == "\\" else 1
2155 return index + 1
2156 if char != "{":2156 ↛ 2157line 2156 didn't jump to line 2157 because the condition on line 2156 was never true
2157 return None
2158 depth = 0
2159 index = at
2160 while index < len(text):2160 ↛ 2175line 2160 didn't jump to line 2175 because the condition on line 2160 was always true
2161 char = text[index]
2162 if char in "\"'":
2163 stop = _item_end(text, index)
2164 if stop is None:2164 ↛ 2165line 2164 didn't jump to line 2165 because the condition on line 2164 was never true
2165 return None
2166 index = stop
2167 continue
2168 if char in "{[":
2169 depth += 1
2170 elif char in "}]":
2171 depth -= 1
2172 if depth == 0:
2173 return index + 1
2174 index += 1
2175 return None
2176
2177
2178def _reads_as(array: _Array, values: Iterable[object]) -> bool:(empty)
2179 """Whether *array*'s entries are *values*, one for one, as TOML reads them."""
2180 found = list(values)
2181 if len(array.entries) != len(found):
2182 return False
2183 # The text parses as TOML already, so each entry's text does too.
2184 return all(
2185 tomllib.loads(f"value = {entry.text}")["value"] == value
2186 for entry, value in zip(array.entries, found, strict=True)
2187 )
2188
2189
2190def _array_text(array: _Array, entries: Iterable[_Entry]) -> str:(empty)
2191 """*array* written again holding *entries*, each with its comments.
2192
2193 One line stays one line. A multi-line array puts each entry on a
2194 line of its own, after the lines above it and with its comment
2195 after it, and keeps the comment after its opening bracket and the
2196 lines before its closing one.
2197 """
2198 if not array.multiline:
2199 return array.key + ", ".join(entry.text for entry in entries) + "]"
2200 margin = array.key[: len(array.key) - len(array.key.lstrip())]
2201 lines = [array.key + (f" {array.head}" if array.head else "")]
2202 for entry in entries:
2203 lines += entry.above
2204 after = f" {entry.after}" if entry.after else ""
2205 lines.append(f"{array.indent}{entry.text},{after}")
2206 lines += array.tail
2207 lines.append(f"{margin}]")
2208 return "\n".join(lines)
2209
2210
2211def available_extensions((empty)
2212 listed: tuple[str, ...], advertised: list[tuple[str, str]] | None = None
2213) -> list[tuple[str, str]]:
2214 """Installed extensions the contract does not list, as (name, distribution).
2215
2216 *advertised* is every ``workshop.extensions`` entry point as
2217 (name, distribution); read from the installed metadata when None.
2218 A footman plugin that declares no extension is not one, and is
2219 never offered. Listing is the only activation channel, so these
2220 do nothing until the contract names them, and the doctor says so.
2221 """
2222 if advertised is None:
2223 advertised = [
2224 (name, entry.dist.name if entry.dist is not None else "")
2225 for name, entry in sorted(_declared().items())
2226 ]
2227 return [(name, dist) for name, dist in advertised if name not in listed]