1"""Ask a typed question that extensions answer, combined by the query's declared rule.
3A query is declared, by the base in the ``[queries]`` section of its
4``contract.toml`` and by an extension under ``[queries.<name>]`` in its
5``extension.toml``, in one grammar ([livery.workshop._queries.QuerySpec][]):
6``combine``, how the answers make one, ``union``, ``nearest``, ``agreed``
7or a function ``module:name``; ``level``, ``package`` for a question
8about one package and ``workspace`` for one about the workspace;
9``default``, the answer while no extension answers; and ``values``, the
10only answers it takes. [livery.workshop._queries.declared_queries][] is
11every declared query by name, the base's and then each installed
12extension's; two extensions declaring one query refuse naming both.
14An extension answers a query under ``[queries]`` in its declaration
15file: ``<name> = "module:function"``, a function called with the
16package or the workspace root, or a literal, ``[queries.<name>] value``.
17It answers under ``[for.<target>.queries]`` the same way, and that
18answer is asked only while the target is listed and the extension's
19listing contributes to it, the rule
20[livery.workshop.contributions_for][] reads a target's tables by.
21[livery.workshop.answer][] asks a package's set, or the installed set,
22in composition order, and combines the answers by the query's rule. A
23handle, [livery.workshop.Query][], names a query and types its answer;
24the base's handles are the constants here, and an extension names its
25own with ``Query("docs.members")``.
26"""
37 from livery.forge import Registry
38 from livery.git import Keyed, Series
39 from livery.workshop._composition import Lookup
40 from livery.workshop._declaration import Declaration, DeclaredValue, Reference
41 from livery.workshop._influence import Changes
42 from livery.workshop._packages import Package, SourceReferences
47#: The levels a query is asked at: about one package, or about the
48#: workspace.
53#: The rules a query may combine its answers by, beside a function.
58#: The extension that declares the base's queries.
61#: How answers, by extension, make one answer; the lookup reads the
62#: declarations a rule needs, the requirements for ``nearest``.
67 """A query asked or answered in a way its declaration cannot take.
69 A name no extension declares, a question asked at the other level,
70 an answer off the query's values, or answers its rule cannot
71 combine; the message names the query and the extensions.
72 """
77 """A handle naming a declared query, typed by its answer.
79 The handle is covariant in its answer: one typed by a tuple serves
80 a reader that takes any iterable.
82 Attributes:
83 name: The key an extension answers it under: ``public-modules``.
84 """
91 """A query as its declarer declares it: one ``[queries.<name>]`` table.
93 Attributes:
94 name: The key an extension answers it under: ``public-modules``.
95 combine: How the answers make one. ``union``: every item any
96 answer holds, once each, in the order first met, each
97 answer a list. ``nearest``: the answer of the one extension
98 no other answering one requires. ``agreed``: the one value
99 every answer that is not empty holds. Or a function, called
100 with the answers by extension and the declarations' lookup,
101 which raises [livery.workshop._queries.QueryError][] or
102 ``ValueError`` naming the extensions when the answers break
103 its rule.
104 level: ``package`` for a question about one package, asked with
105 the package and answered by its set in composition order;
106 ``workspace`` for one about the workspace, asked with its
107 root and answered by the installed set in composition order.
108 default: The answer while no extension answers; None takes the
109 rule's answer over no answers, an empty union, no nearest,
110 no agreement, a function's answer over nothing.
111 values: The only answers the query takes; None takes any.
112 extension: The extension that declares it; the base for its own.
113 """
124 """Every item any answer holds, once each, in the order first met."""
125 del lookup
126 found: dict[Any, None] = {}
127 for name, value in answers.items():
128 if isinstance(value, (str, bytes)) or not isinstance(value, Iterable):
129 raise QueryError(
130 f"{name} answers {value!r}, and a union combines lists; answer a list"
131 )
132 found.update(dict.fromkeys(value))
133 return tuple(found)
137 """The one value every answer that is not empty holds; empty when none does."""
138 del lookup
139 named = {name: value for name, value in answers.items() if value}
140 if len({repr(value) for value in named.values()}) > 1:
141 listed = ", ".join(f"{name} {value!r}" for name, value in named.items())
142 raise QueryError(f"the answers differ, and they must agree: {listed}")
143 return next(iter(named.values()), "")
147 """The answer of the one extension no other answering one requires.
149 Its answer is the nearest: it builds on the others. None when no
150 extension answers with a value.
151 """
152 from livery.workshop._composition import nearest_extensions
154 named = {name: value for name, value in answers.items() if value is not None}
155 nearest = nearest_extensions(named, lookup)
156 if len(nearest) > 1:
157 raise QueryError(
158 f"{' and '.join(nearest)} both answer, and neither requires the other;"
159 " one of them answers, or one requires the other"
160 )
161 return named[nearest[0]] if nearest else None
165 """Every name any answer holds, to its one value; a name valued twice refuses.
167 The rule of the ``requirements``, ``test-requirements`` and
168 ``job-built-members`` queries, which the base's contract file names.
169 """
170 del lookup
171 found: dict[str, str] = {}
172 by: dict[str, str] = {}
173 for name, value in answers.items():
174 for key, held in cast("Mapping[str, str]", value).items():
175 if key in found and found[key] != held:
176 raise QueryError(
177 f"{by[key]} answers {key} {found[key]!r} and {name} answers"
178 f" {held!r}; the answers name each entry once, or alike"
179 )
180 found[key] = held
181 by.setdefault(key, name)
182 return found
186 """Every item any answer holds; an item two extensions answer refuses.
188 The ``executables`` query's rule, which the base's contract file
189 names.
190 """
191 del lookup
192 owners: dict[str, str] = {}
193 for name, value in answers.items():
194 for item in cast("Iterable[str]", value):
195 if item in owners and owners[item] != name:
196 raise QueryError(
197 f"{owners[item]} and {name} both answer {item}; one extension"
198 " of a package answers each"
199 )
200 owners[item] = name
201 return tuple(owners)
204#: Each rule by its name in a declaration.
209 """Write a package's requirement on a sibling into one ecosystem's manifest.
211 An extension answers the ``requirement-writers`` query with its
212 writers, and the ``test-requirement-writers`` query with the writers
213 of a requirement the package's tests alone have. Every writer of a
214 package's set is called for each requirement. A writer takes a
215 sibling of its own ecosystem alone: for any other sibling it writes
216 nothing and returns None, so the requirement lands in the manifest
217 of the sibling's ecosystem. A requirement no writer of the set
218 takes refuses, naming the sibling's set.
219 """
222 self, package: Package, dependency: Package, floor: str
223 ) -> list[str] | None:
224 """Write *dependency* at *floor* into *package*'s manifest.
226 Args:
227 package: The package whose manifest gains the requirement.
228 dependency: The sibling it requires.
229 floor: The lowest version of *dependency* the requirement
230 takes.
232 Returns:
233 The files changed, relative to the package; empty when the
234 manifest names *dependency* already. None for a sibling
235 outside the writer's ecosystem, which it leaves alone.
236 """
237 ...
241 """Fold one file a check leg's shards each left into the platform leg's one file.
243 An extension answers the ``ci.fold`` query with one folder per file
244 its leg entry leaves in the leg's spool, by the file's name. The
245 gate job calls it with the shards' files, in shard order, each as
246 the per-run ref holds it, and puts what it returns on the platform
247 leg's ref under the same name, where the judges read it as one
248 leg's file.
249 """
252 """The one file of the platform leg, from *shards*' files.
254 Args:
255 shards: The file as each shard left it, in shard order.
257 Returns:
258 The folded file.
260 Raises:
261 ValueError: When the shards' files cannot be one leg's,
262 naming what differs; the fold is red with it.
263 """
264 ...
267#: The modules that declare the package's public API, by import path:
268#: what a type-completeness step verifies.
271#: Where the package's build writes its compilation database, which a
272#: tool such as clang-tidy reads.
275#: The names other packages reference this one's code by.
278#: What each of the package's sources references, one record per
279#: source, which the layering phase's rules over references read.
282#: The version the package's own manifests declare.
285#: Every file the ``stamp`` phase may write a version into, so a caller
286#: can keep and restore them.
289#: What the package's native manifests require, each distribution's name
290#: to its constraint.
293#: The writers of a requirement on a sibling into the package's native
294#: manifests, each for a sibling of its own ecosystem; every one is called.
297#: What the package's native manifests require for its tests alone, each
298#: distribution's name to its constraint. A package whose set answers it
299#: has a home for its test edges.
302#: The writers of a test requirement on a sibling into the package's
303#: native manifests, each for a sibling of its own ecosystem; every one is
304#: called.
306 "test-requirement-writers"
307)
309#: The distributions the package releases, each as its ecosystem and its
310#: name.
313#: The registry the package releases to, as a probe of the versions it
314#: serves, which the release train polls until an upload is served; an
315#: empty answer when no extension of the package's set releases it.
318#: The executables ``fm run`` may start, by name.
321#: What the host must provide for the package and no store installs,
322#: such as a C compiler, each by the name it resolves by on ``PATH``.
325#: The marketplace ids of the editor extensions the listed extensions
326#: recommend, which the rendered ``.vscode/extensions.json`` lists.
329#: The state store's series the listed extensions keep beside the
330#: base's own, which the janitor bounds and ``fm store.ls`` lists.
333#: The members a job of the release point builds before the wave, each
334#: member's path (``packages/<member>``) to the job's name: the wave
335#: publishes what the run collected for them, and the entry installs
336#: those of them uv installs after the tools.
339#: The inputs the listed extensions add to the checkout step of the
340#: rendered GitHub and Gitea workflows, each name to its value.
343#: How the gate job folds a file a check leg's shards each left into the
344#: platform leg's one file, by the file's name: one folder per file the
345#: listed extensions' leg entries leave. A file two extensions fold
346#: refuses; a file nobody folds is red by name in the fold.
349#: What one answer to `REACHES` says of a change: each changed path it
350#: widens, to why it widens and the paths of the members it reaches.
353#: What a change reaches beyond its own packages and their dependents:
354#: the functions the listed extensions answer with, each called with the
355#: run's [livery.workshop.Changes][]. The affected engine
356#: ([livery.workshop._graph.affected_from_paths][]) runs every member
357#: they name, with its dependents.
363 """The base's queries, read from the ``[queries]`` section of its contract file.
365 In the file's order, each spec naming the base as its declarer.
367 Raises:
368 DeclarationError: when a section is off the shape a query's
369 declaration has.
370 """
371 from livery.workshop._contract_keys import BASE_FILE, base_contract
372 from livery.workshop._declaration import query_specs_of
374 return query_specs_of(base_contract(), BASE_FILE, extension=BASE, package=BASE)
379 """Every declared query by name: the base's, then each installed extension's.
381 An installed extension's declaration is read whether the workspace
382 lists it or not, so an answer to its query reads the same anywhere;
383 a query nobody listed declares is asked by nobody.
385 Raises:
386 DeclarationError: when two extensions declare one query.
387 """
388 from livery.footman import installed_entry_points
389 from livery.workshop._declaration import DeclarationError, query_declarations
391 found = dict(base_queries())
392 for entry in installed_entry_points("workshop.extensions"):
393 for spec in query_declarations(entry.name, entry.value.partition(":")[0]):
394 held = found.get(spec.name)
395 if held is not None and held.extension != spec.extension:
396 both = " and ".join(sorted((held.extension, spec.extension)))
397 raise DeclarationError(
398 f"the {spec.name} query is declared by both {both}; one"
399 " extension declares a query"
400 )
401 found[spec.name] = spec
402 return found
406 """The declared query *name*; refuses naming the declared ones.
408 Raises:
409 QueryError: when no extension declares *name*.
410 """
411 specs = declared_queries()
412 found = specs.get(name)
413 if found is None:
414 raise QueryError(
415 f"{name} is not a declared query; the queries are {', '.join(specs)}"
416 )
417 return found
421 """The extensions asked *spec* about *subject*, in the order they answer.
423 A package's set, or the installed set, in composition order; a set
424 whose declared order has no start is asked
425 alphabetically, and ``layering.graph`` names the cycle.
427 Raises:
428 QueryError: when *subject* is at the other level from the query.
429 """
430 if isinstance(subject, Path):
431 if spec.level != WORKSPACE_LEVEL:
432 raise QueryError(
433 f"{spec.name} is a question about a package, which {spec.extension}"
434 " declares at the package level; ask it with the package"
435 )
436 from livery.workshop._extensions import extension_names
438 return extension_names(subject)
439 if spec.level != PACKAGE_LEVEL:
440 raise QueryError(
441 f"{spec.name} is a question about the workspace, which {spec.extension}"
442 " declares at the workspace level; ask it with the workspace root"
443 )
444 from livery.workshop._composition import OrderCycle, closure, order
446 members = closure(subject.extensions, lookup)
447 try:
448 return order(members, lookup)
449 except OrderCycle:
450 return tuple(sorted(members))
454 """The listed targets *extension*'s listing contributes to in *subject*'s workspace.
456 The rule [livery.workshop.contributions_for][] reads a target's
457 tables by: every listed target the extension declares a
458 ``[for.<target>]`` table for, except those its root entry's
459 ``without`` names.
460 """
461 from livery.workshop._extensions import extension_names, resolved_targets
463 start = subject if isinstance(subject, Path) else subject.directory
464 listed = frozenset(extension_names(start))
465 return listed.intersection(resolved_targets(start).get(extension, ()))
469 subject: Package | Path, extension: str, declared: Declaration, query: str
470) -> list[tuple[tuple[str, ...], Reference | DeclaredValue]]:
471 """Where *extension* answers *query* about *subject* now, each place and answer.
473 A place is a key path in *declared*'s file: the top level,
474 ``queries.<query>``, always, and a ``[for.<target>]`` table's,
475 ``for.<target>.queries.<query>``, while *target* is listed and the
476 extension's listing contributes to it. Decided from the
477 declarations and the contracts' lists alone, asking nothing; empty
478 when no place answers now. [livery.workshop._queries.answers][]
479 asks the places it names.
480 """
481 held: list[tuple[tuple[str, ...], Reference | DeclaredValue]] = []
482 if query in declared.queries:
483 held.append((("queries", query), declared.queries[query]))
484 targets = [
485 target
486 for target, answered in declared.target_queries.items()
487 if query in answered
488 ]
489 if targets:
490 # The lists are read only when a [for] table answers the query.
491 contributed = _contributed(subject, extension)
492 held += [
493 (("for", target, "queries", query), declared.target_queries[target][query])
494 for target in targets
495 if target in contributed
496 ]
497 return held
501 name: str,
502 held: list[tuple[tuple[str, ...], Reference | DeclaredValue]],
503 subject: Package | Path,
504 spec: QuerySpec,
505) -> object:
506 """The answer of the extension *name* from each place *held* names.
508 Each place is a key path in the declaration file and the answer
509 there, asked and judged against the query's values. Answers from
510 two places make one for a ``union`` query, every item once in the
511 order first met; for a query of any other rule they refuse.
512 """
513 from livery.workshop._contract_keys import shown
514 from livery.workshop._declaration import DeclaredValue
516 values: dict[str, object] = {}
517 for place, answered in held:
518 value = (
519 answered.value if isinstance(answered, DeclaredValue) else answered(subject)
520 )
521 if spec.values is not None and value not in spec.values:
522 listed = ", ".join(repr(known) for known in spec.values)
523 at = f" at {shown(place)}" if place[0] == "for" else ""
524 raise QueryError(
525 f"{name} answers {spec.name} with {value!r}{at}, whose values are"
526 f" {listed}"
527 )
528 values[shown(place)] = value
529 if len(values) == 1:
530 return next(iter(values.values()))
531 if spec.combine != UNION:
532 raise QueryError(
533 f"{name} answers {spec.name} at {' and at '.join(values)}; only a"
534 " union query takes two answers from one extension, so answer it in"
535 " one place"
536 )
537 items: dict[object, None] = {}
538 for where, value in values.items():
539 if isinstance(value, (str, bytes)) or not isinstance(value, Iterable):
540 raise QueryError(
541 f"{name} answers {spec.name} with {value!r} at {where}, and a union"
542 " combines lists; answer a list"
543 )
544 items.update(dict.fromkeys(cast("Iterable[object]", value)))
545 return tuple(items)
549 subject: Package | Path, query: Query[T], *, lookup: Lookup | None = None
550) -> dict[str, T]:
551 """Each extension that answers *query* about *subject*, to its answer.
553 *subject* is the package for a package-level query, and the
554 workspace root, or a directory in the workspace, for a
555 workspace-level one. Each declaration is read through *lookup*,
556 the installed ones when absent. An extension answers at the top
557 level of its declaration file, and in a ``[for.<target>]`` table
558 while *target* is listed and the extension's listing contributes to
559 it ([livery.workshop._queries.answered_at][]); answering in two of
560 those places, it answers a ``union`` query with every item of both.
562 Raises:
563 QueryError: when no extension declares the query, when *subject*
564 is at the other level, when an answer is off the query's
565 values, naming the extension, or when an extension answers a
566 query of another rule in two places, naming both.
567 """
568 if lookup is None:
569 from livery.workshop._extensions import installed_declaration
571 lookup = installed_declaration
572 spec = query_spec(query.name)
573 found: dict[str, T] = {}
574 for name in _walk(subject, spec, lookup):
575 declared = lookup(name)
576 if declared is None:
577 continue
578 held = answered_at(subject, name, declared, query.name)
579 if held:
580 found[name] = cast("T", _one_answer(name, held, subject, spec))
581 return found
585 subject: Package | Path, query: Query[T], *, lookup: Lookup | None = None
586) -> T:
587 """The answer to *query* about *subject*: the extensions' answers, combined.
589 *subject* is the package for a package-level query, answered by its
590 set in composition order, and the workspace root, or a directory in
591 the workspace, for a workspace-level one, answered by the installed
592 set in composition order. With no extension answering, the query's
593 declared default, or its rule's answer over nothing.
595 Raises:
596 QueryError: when no extension declares the query, when *subject*
597 is at the other level, when an answer is off the query's
598 values, or when the answers break the query's rule; the
599 message names the query and the extensions, and a package's
600 path for a package-level query.
601 """
602 if lookup is None:
603 from livery.workshop._extensions import installed_declaration
605 lookup = installed_declaration
606 spec = query_spec(query.name)
607 found = answers(subject, query, lookup=lookup)
608 if not found and spec.default is not None:
609 return cast("T", spec.default)
610 combine: Combine = (
611 RULES[spec.combine] if isinstance(spec.combine, str) else spec.combine
612 )
613 where = "" if isinstance(subject, Path) else f"{subject.path}: "
614 try:
615 return cast("T", combine(found, lookup))
616 except (QueryError, ValueError) as error:
617 raise QueryError(f"{where}{query.name}: {error}") from None
621 """Every workspace-level query's answer about *root*, by name.
623 A rendered template reads ``queries["python.dev-group"]`` through
624 it; a name no extension declares at the workspace level is absent.
625 """
626 return {
627 name: answer(root, Query(name), lookup=lookup)
628 for name, spec in declared_queries().items()
629 if spec.level == WORKSPACE_LEVEL
630 }