Coverage for packages/workshop/src/livery/workshop/_templates.py: 94%

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 workspace's generated files: the drift check, the writer, new members.
2
3The listed extensions' files are composed by the fragment engine
4(`livery.workshop._shipped_files`); the CI files and the codeowners file
5are generated from the contract. `drift_check` judges both against the
6repository as the gate's `fm drift.check`; `apply_project` writes both,
7and `fm sync` runs it, which is the recovery for drift.
8
9Each installed template is a verb, ``fm new.package.<template> <name>
10--<option>=<answer>``, made from its declaration by
11`generate_template_verbs` when the plugin loads. It writes a member
12born from the template into ``packages/<name>`` through
13`render_member` (`livery.workshop._seeds`), the one function every
14creation calls, and a fresh runner adds the member to the project
15files.
16"""
17
18from __future__ import annotations(empty)
19
20import inspect(empty)
21import re(empty)
22import weakref(empty)
23from collections.abc import Callable, Mapping, Sequence(empty)
24from pathlib import Path(empty)
25from typing import TYPE_CHECKING, Annotated, Any, Literal, cast(empty)
26
27import livery.footman as footman(empty)
28from livery.footman import Group, doc, fail, group(empty)
29from livery.workshop._contract import load_contract(empty)
30from livery.workshop._extensions import ((empty)
31 stack_entries,
32 workspace_root,
33)
34from livery.workshop._identity import default_description, identity, python_dirs(empty)
35from livery.workshop._pythons import python_floor, runner_script(empty)
36
37if TYPE_CHECKING:(empty)
38 from livery.workshop._declaration import DeclaredTemplate, TemplateOption
39
40#: What ``fm new`` does, and what ``fm new.package`` does.
41NEW_HELP = "Create a project from the extensions' seeds, or a package from a template"(empty)
42PACKAGE_HELP = "Create a package from an installed template: one task per template"(empty)
43
44new = group("new", help=NEW_HELP)(empty)
45
46#: The group of the templates' verbs: ``fm new.package.<template>``.
47package = new.group("package", help=PACKAGE_HELP)(empty)
48
49
50def _root() -> Path:(empty)
51 """The workspace root, or fail."""
52 root = workspace_root()
53 if root is None:53 ↛ 54line 53 didn't jump to line 54 because the condition on line 53 was never true
54 fail("no workspace: no workshop.toml above the working directory")
55 return root
56
57
58def _requirement_name(spec: str) -> str:(empty)
59 """The distribution a requirement spec names, extras and floors cut."""
60 return re.split(r"[\[<>=!~; ]", spec.strip(), maxsplit=1)[0]
61
62
63def registry_injections(root: Path) -> dict[str, str]:(empty)
64 """The contract's python registry, as render inputs.
65
66 Only the committed ``[registries]`` table feeds a render: the
67 resolution ladder's environment rung is machine truth, and a
68 rendered file must derive from the repository alone or the drift
69 check would judge each machine differently. Nothing declared
70 renders nothing, and uv resolves from the ecosystem default.
71 """
72 contract = load_contract(root / "workshop.toml")
73 table = contract.get("registries") or {}
74 entry = table.get("python") if isinstance(table, dict) else None
75 url, prerelease = "", ""
76 if isinstance(entry, str):
77 url = entry
78 elif isinstance(entry, dict):
79 url = str(entry.get("url", ""))
80 prerelease = str(entry.get("prerelease", ""))
81 return {"python_registry": url, "python_prerelease": prerelease}
82
83
84def render_injections(root: Path, answers: dict[str, Any]) -> dict[str, Any]:(empty)
85 """The render-time values no answer stores.
86
87 Identity is answered, configuration is declared: the runner's
88 name belongs to the process, the Python floor to the root
89 ``pyproject.toml``, the extensions and the registry to
90 ``workshop.toml``. Every project render mixes these in, so the
91 answers hold identity and the ``packages`` roster alone.
92 """
93 entries = stack_entries(root)
94 if not entries:94 ↛ 95line 94 didn't jump to line 95 because the condition on line 94 was never true
95 fail(
96 "workshop.toml declares no [workspace] extensions: the render"
97 " needs the stack (the base extension is livery.workshop)"
98 )
99 members = {
100 _requirement_name(str(entry.get("dev", "")))
101 for entry in answers.get("packages", [])
102 if isinstance(entry, dict)
103 }
104 from livery.workshop._queries import EDITOR_EXTENSIONS, answer, workspace_answers
105
106 injected: dict[str, Any] = {
107 "runner_prog": footman.prog(),
108 "python_floor": python_floor(root),
109 # The workspace's own tests directory, which the checkers and
110 # the test runner read only while it exists: a newborn has none.
111 "root_tests": ["tests"] if (root / "tests").is_dir() else [],
112 # Each python member's src and tests that hold a python file: a
113 # checker such as mypy refuses a named directory with none, and
114 # an extension's src may hold data alone.
115 "python_dirs": python_dirs(root),
116 # The workspace-level queries' answers, by name, each answered
117 # when a template reads it: the dev group's tool lines, the docs
118 # group's lines, pytest's addopts. A listed extension's answer
119 # lands here, and an unlisted one's leaves with it.
120 "queries": workspace_answers(root),
121 "extension_imports": [import_path for import_path, _ in entries],
122 # One line per distribution: a wheel may ship several extensions.
123 "extension_requirements": _extension_requirements(entries, members),
124 # The editor extension ids the listed extensions answer.
125 "extensions": list(answer(root, EDITOR_EXTENSIONS)),
126 **registry_injections(root),
127 }
128 injected["fragments"] = compose_fragments({**answers, **injected})
129 return injected
130
131
132def _extension_requirements((empty)
133 entries: tuple[tuple[str, str], ...], members: set[str]
134) -> list[str]:
135 """The dev group's line for each stack distribution that is not a member.
136
137 One line per distribution, since a wheel may ship several
138 extensions.
139 """
140 found = [dist for _name, dist in entries if _requirement_name(dist) not in members]
141 return list(dict.fromkeys(found))
142
143
144def compose_fragments(data: dict[str, Any]) -> dict[str, str]:(empty)
145 """The step records' fragments composed per rendered file over *data*."""
146 from livery.workshop._fragments import compose_project
147
148 return compose_project(fragment_data(data))
149
150
151def fragment_data(data: dict[str, Any]) -> dict[str, Any]:(empty)
152 """*data* with what the step records' fragments read beside it.
153
154 The roster is split the way the project file splits it, ``py`` for
155 the members with a dev entry and ``native`` for the rest, and the
156 per-file ignores the claims render are added for the sets of
157 extensions the members hold, each entry's ``extensions``. A roster
158 with no member renders the ignores of the
159 workspace's own unit alone. The fragment engine reads the step
160 records' fragments through this.
161 """
162 from livery.workshop._steps import per_file_ignores
163
164 roster = [entry for entry in data.get("packages", []) if isinstance(entry, dict)]
165 held = {
166 tuple(str(name) for name in entry.get("extensions", ())) for entry in roster
167 }
168 return {
169 **data,
170 "py": [entry for entry in roster if entry.get("dev")],
171 "native": [entry for entry in roster if not entry.get("dev")],
172 # The per-file ignores the claims render, for the sets present.
173 "per_file_ignores": per_file_ignores(sorted(held)),
174 }
175
176
177def package_injections(root: Path) -> dict[str, Any]:(empty)
178 """The render-time values a package render takes from the contract.
179
180 The forge facts feed the changelog's link bases; asking them per
181 package would let one workspace's packages disagree about where
182 they live.
183 """
184 contract = load_contract(root / "workshop.toml")
185 forge_table = contract.get("forge") or {}
186
187 return {
188 "runner_prog": footman.prog(),
189 "python_floor": python_floor(root),
190 "forge_kind": str(forge_table.get("kind", "github")),
191 "forge_owner": str(forge_table.get("owner", "")),
192 "forge_url": str(forge_table.get("url", "")),
193 "project_name": identity(root)["project_name"],
194 }
195
196
197def _lf(data: bytes) -> bytes:(empty)
198 """The bytes with LF endings, whatever the platform wrote.
199
200 Git holds LF, and a file written on Windows may carry CRLF, so both
201 sides normalise before any compare or write. Without this the
202 Windows gate drifts on every file.
203 """
204 return data.replace(b"\r\n", b"\n")
205
206
207def project_drift(root: Path) -> list[str]:(empty)
208 """The drift report: generated files (CI, codeowners) that disagree with *root*.
209
210 Empty when every generated file matches the repository byte for
211 byte.
212 """
213 drift: list[str] = []
214 from livery.workshop._ci_generate import generated_files
215 from livery.workshop._governance import codeowners_file
216
217 generated = dict(generated_files(root))
218 rendered_owners = codeowners_file(root)
219 if rendered_owners is not None:219 ↛ 220line 219 didn't jump to line 220 because the condition on line 219 was never true
220 from livery.workshop._provenance import generated_header
221
222 generated[root / rendered_owners.path] = (
223 generated_header("#") + rendered_owners.content
224 )
225 for path, content in generated.items():
226 relative_generated = path.relative_to(root).as_posix()
227 if not path.is_file():
228 drift.append(
229 f"{relative_generated}: generated, but missing from the repository"
230 )
231 elif _lf(path.read_bytes()) != _lf(content.encode()):231 ↛ 232line 231 didn't jump to line 232 because the condition on line 231 was never true
232 drift.append(f"{relative_generated}: differs from its generation")
233 from livery.workshop._ci_generate import retired_files
234
235 for path in retired_files(root):235 ↛ 236line 235 didn't jump to line 236 because the loop on line 235 never started
236 drift.append(
237 f"{path.relative_to(root).as_posix()}: retired, still present;"
238 " the apply deletes it"
239 )
240 return drift
241
242
243def _release_baseline(directory: Path) -> str:(empty)
244 """The [release] baseline a package's contract declares, or empty.
245
246 A migrated distribution's version line predates this workspace;
247 the baseline names the version it continues from, and a package
248 template reads it as ``release_baseline`` to anchor the first
249 release on it.
250 """
251 contract = directory / "workshop.toml"
252 if not contract.is_file():
253 return ""
254 data = load_contract(contract)
255 return str((data.get("release") or {}).get("baseline", ""))
256
257
258def apply_project(root: Path) -> list[str]:(empty)
259 """Write the composed and generated files over *root*; the files that changed.
260
261 The fragment engine composes the project file, the editor files, the
262 ignore and attribute lines, so a new member reaches `pyproject.toml`
263 here; the CI files and the codeowners file are generated after.
264 """
265 changed: list[str] = []
266 from livery.workshop._shipped_files import deliver
267
268 for line in deliver(root):
269 verb, _, rest = line.strip().partition(" ")
270 path = rest.partition(":")[0].split(" ")[0]
271 if path.startswith((".workshop/", ".claude/")):
272 continue # this checkout's own, not the project's render
273 if verb in ("wrote", "updated", "removed"):273 ↛ 276line 273 didn't jump to line 276 because the condition on line 273 was always true
274 changed.append(path)
275 else:
276 print(line)
277 changed.extend(apply_generated(root))
278 return changed
279
280
281def apply_generated(root: Path) -> list[str]:(empty)
282 """Write the emitted artifacts (CI files, codeowners); what changed.
283
284 The fragment engine's delivery and this together are apply_project,
285 which an update runs, so an instance's generated workflows move
286 with its workshop.
287 """
288 changed: list[str] = []
289 from livery.workshop._ci_generate import generated_files
290 from livery.workshop._governance import codeowners_file
291
292 generated = dict(generated_files(root))
293 rendered_owners = codeowners_file(root)
294 if rendered_owners is not None:294 ↛ 295line 294 didn't jump to line 295 because the condition on line 294 was never true
295 from livery.workshop._provenance import generated_header
296
297 generated[root / rendered_owners.path] = (
298 generated_header("#") + rendered_owners.content
299 )
300 for path, content in generated.items():
301 body = _lf(content.encode())
302 if not path.is_file() or _lf(path.read_bytes()) != body:
303 path.parent.mkdir(parents=True, exist_ok=True)
304 path.write_bytes(body)
305 changed.append(path.relative_to(root).as_posix())
306 from livery.workshop._ci_generate import retired_files
307
308 for path in retired_files(root):
309 path.unlink()
310 changed.append(f"{path.relative_to(root).as_posix()} (retired)")
311 return changed
312
313
314def drift_check(files: frozenset[str] | None = None) -> None:(empty)
315 """Fail when a composed or generated file drifts from what writes it.
316
317 The gate's drift check, `fm drift.check`. `fm sync` writes both
318 kinds of file, so it is the recovery for every line this names.
319 *files* keeps the findings to those root-relative files: the tree
320 a change is measured from was judged already, so only a file the
321 change touched can have drifted since, unless an input of every
322 file changed, and then the caller passes None.
323 """
324 from livery.workshop._shipped_files import shipped_drift
325
326 root = _root()
327 drift = shipped_drift(root) + project_drift(root)
328 if files is not None:
329 drift = [line for line in drift if line.split(":", 1)[0] in files]
330 if not drift:
331 return
332 fail(
333 "committed files drift from what writes them:\n "
334 + "\n ".join(drift)
335 + f"\n run `{footman.prog()} sync`, which writes them again"
336 )
337
338
339#: The package's name, which every template's verb takes first. Module
340#: level, where footman reads a task's annotations.
341_Name = Annotated[str, doc("directory name under packages/ (e.g. scratch)")](empty)
342
343#: Each verb the generator made, to what it was made from: the template
344#: and the options its verb offers.
345_MADE: weakref.WeakKeyDictionary[(empty)
346 Callable[..., None], tuple[DeclaredTemplate, tuple[TemplateOption, ...]]
347] = weakref.WeakKeyDictionary()
348
349
350def generate_template_verbs((empty)
351 templates: Mapping[str, DeclaredTemplate], into: Group | None = None
352) -> None:
353 """Make a verb per template, ``fm new.package.<template>``, from *templates*.
354
355 *templates* are the installed ones by name: the base's, and those
356 of each extension of the installed set an installed distribution
357 declares, as the mount read them. Each verb takes the package's
358 name, then each option the template's chain offers as a keyword
359 option (`livery.workshop._seeds.verb_options`): choices as a
360 `Literal`, the doc as its help line, the default as its default,
361 and an option without a default required. Nothing else is read, so
362 the command line, its help and its completion follow from the
363 declarations alone.
364
365 Run again after the installed set changed, it makes the verb of a
366 new template, remakes a verb whose template or options changed, and
367 removes the verb of a template that is gone. A task at a template's
368 address that the generator did not make is left alone.
369 """
370 from livery.footman import root_group
371 from livery.workshop._seeds import verb_options
372
373 parent = _package_group(into if into is not None else root_group)
374 for key, task in list(parent.tasks.items()):
375 if _made(task) is not None and key not in templates:
376 del parent.tasks[key]
377 for name, template in templates.items():
378 options = verb_options(name, templates)
379 existing = parent.tasks.get(name)
380 if existing is not None:
381 made = _made(existing)
382 if made is None or made == (template, options):
383 continue
384 del parent.tasks[name]
385 parent.task(name=name)(_template_verb(template, options))
386
387
388def _package_group(target: Group) -> Group:(empty)
389 """The ``new.package`` group under *target*, made when it is missing."""
390 held = target.groups.get("new")
391 if held is None:
392 held = target.group("new", help=NEW_HELP)
393 found = held.groups.get("package")
394 if found is None:
395 found = held.group("package", help=PACKAGE_HELP)
396 return found
397
398
399def _made((empty)
400 task: Callable[..., object],
401) -> tuple[DeclaredTemplate, tuple[TemplateOption, ...]] | None:
402 """What the generator made *task* from; None for a task it did not make."""
403 return _MADE.get(inspect.unwrap(task))
404
405
406def _template_verb((empty)
407 template: DeclaredTemplate, options: Sequence[TemplateOption]
408) -> Callable[..., None]:
409 """The verb that creates a package from *template*, offering *options*."""
410 born = template.name
411
412 def verb(name: str, **answers: object) -> None:
413 _create(born, name, answers)
414
415 parameters = [
416 inspect.Parameter(
417 "name", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=_Name
418 ),
419 *(_parameter(option) for option in options),
420 ]
421 # footman reads a verb's parameters through inspect.signature, which
422 # answers with __signature__ when a function carries one: the options
423 # are data, so the signature is built here.
424 vars(verb)["__signature__"] = inspect.Signature(parameters, return_annotation=None)
425 verb.__doc__ = _verb_doc(template)
426 _MADE[verb] = (template, tuple(options))
427 return verb
428
429
430def _parameter(option: TemplateOption) -> inspect.Parameter:(empty)
431 """*option* as a keyword option of its template's verb."""
432 from livery.workshop._declaration import OPTION_TYPES
433
434 answer: Any = OPTION_TYPES[option.type]
435 if option.choices:
436 # The choices are data, so the Literal is built at run time.
437 answer = cast("Any", Literal)[option.choices]
438 return inspect.Parameter(
439 option.variable,
440 inspect.Parameter.KEYWORD_ONLY,
441 default=inspect.Parameter.empty if option.default is None else option.default,
442 annotation=cast("Any", Annotated)[answer, doc(option.doc)],
443 )
444
445
446def _verb_doc(template: DeclaredTemplate) -> str:(empty)
447 """The help of *template*'s verb: its doc first, then what a creation does.
448
449 The first line is the summary listings show, so it stays one line;
450 the paragraphs after it are wrapped as a docstring is, since footman
451 prints a verb's help as written.
452 """
453 import textwrap
454
455 extends = (
456 f", after the files of {template.extends} and each template it extends"
457 if template.extends
458 else ""
459 )
460 paragraphs = (
461 "Writes the package-base seeds, then the files of the template"
462 f" {template.name}{extends}, into packages/<name>, with the"
463 " distribution named <namespace>-<name> and the contract listing"
464 " the template's extensions. Each option's answer is checked"
465 " before anything is written, and renders the files; nothing"
466 " stores it.",
467 "A creation installs nothing: a template that needs an extension"
468 " the workspace's lists do not hold, or that no installed"
469 " distribution declares yet, refuses before anything is written,"
470 " naming each. Then the runner the workspace's environment holds"
471 " wires the member, run as `new.wire <name>`: it writes the"
472 " project files again, and locks and syncs the environment and"
473 " the tools.",
474 )
475 wrapped = (
476 textwrap.fill(paragraph, 72, break_on_hyphens=False) for paragraph in paragraphs
477 )
478 return "\n\n".join((f"Create {template.doc}.", *wrapped))
479
480
481def _create(template: str, name: str, answers: Mapping[str, object]) -> None:(empty)
482 """Create ``packages/<name>`` from *template* with *answers*, then wire it.
483
484 The body of every template's verb: the render (`render_member`),
485 then the wiring in the runner the workspace's environment holds, a
486 fresh process whose mount holds the member's extensions.
487 """
488 root = _root()
489 render_member(root, name, template, answers)
490 prog = footman.prog()
491 runner = runner_script(root / ".venv")
492 if not runner.is_file():
493 fail(
494 f"{runner} is missing: {root}'s environment has no {prog} to wire"
495 f" packages/{name} with. `uv sync` in {root} installs it; then run"
496 f" `{prog} new.wire {name}` there"
497 )
498 print(f" packages/{name}: seeded; the wiring continues with {runner}")
499 footman.run([str(runner), "new.wire", name], cwd=root, capture=False)
500
501
502@new.task(name="wire", hidden=True)(empty)
503def new_wire(name: _Name) -> None:(empty)
504 """Wire the package under packages/<name> into the workspace.
505
506 Writes the project files again, so every per-package list picks the
507 member up, then locks and syncs the environment and the tools. A
508 template's verb runs it in the runner the workspace's environment
509 holds once the member is written, and it is the recovery after a
510 wiring that stopped part way. A member that does not hold python
511 joins the roster without a dev-group entry: there is no
512 distribution to install.
513 """
514 wire_member(_root(), name)
515
516
517def wire_member(root: Path, name: str) -> None:(empty)
518 """Wire the package under ``packages/<name>`` into *root*.
519
520 Writes the composed and generated files again, so every
521 per-package list picks the member up, then locks and syncs the
522 environment and the tools. ``fm new.wire`` runs it in the runner
523 the workspace's environment holds, after a template's verb wrote the
524 member.
525
526 Raises:
527 Failed: when *name* breaks the package naming rule, or
528 ``packages/<name>`` holds no package.
529 """
530 _check_member_name(name)
531 if not (root / "packages" / name / "workshop.toml").is_file():
532 fail(
533 f"packages/{name} holds no package to wire:"
534 f" `{footman.prog()} new.package.<template> {name}` creates one"
535 )
536 for changed in apply_project(root):
537 print(f" rendered: {changed}")
538 from livery.workshop._tool_tasks import sync_tools
539 from livery.workshop._uv import run_uv
540
541 run_uv("lock", root=root)
542 run_uv("sync", root=root)
543 # A member's extensions bring tools of their own (a native
544 # member's build tools and the steps that judge it), so the tool
545 # lock moves with the member and the store supplies what it names:
546 # the gate that follows finds them, as it does after a birth.
547 sync_tools(root)
548 print(f" packages/{name}: seeded, wired, and installed")
549
550
551def _check_member_name(name: str) -> None:(empty)
552 """Refuse a package name ``packages/<name>`` cannot hold."""
553 if not re.fullmatch(r"([a-z][a-z0-9-]*/)?[a-z][a-z0-9-]*", name):
554 fail(
555 f"package name {name!r}: use lowercase letters, digits, hyphens,"
556 " and at most one group directory (extensions/widgets)"
557 )
558
559
560def render_member((empty)
561 root: Path,
562 name: str,
563 template: str,
564 answers: Mapping[str, object] | None = None,
565) -> str:
566 """Write a member born from *template* into ``packages/<name>``; the import path.
567
568 The one function behind every creation: each template's verb, ``fm
569 ci.scale``, and ``fm new.project --extension`` call it. Writes the
570 ``package-base`` seeds and the files of the template's chain
571 (`livery.workshop._seeds.create_package`), rendered with *answers*,
572 each answer to one of the chain's options by its variable, and the
573 files the records compose for the member. The member's own contract
574 is one of the template's files, and discovery finds the member
575 through it, so the roster needs no write. The project files, the
576 lock and the install are the caller's: `wire_member` runs them for
577 one member, and a caller adding many members runs them once after
578 the last. Refuses an existing directory, naming it, a template the
579 birth cannot take, and an answer the template's options refuse,
580 before anything is written.
581 """
582 _check_member_name(name)
583 destination = root / "packages" / name
584 if destination.exists():
585 fail(f"{destination} already exists")
586 group = destination.parent
587 if group.name != "packages" and (group / "workshop.toml").is_file():587 ↛ 588line 587 didn't jump to line 588 because the condition on line 587 was never true
588 fail(f"{group} is a package: a group directory has no workshop.toml")
589 facts = identity(root)
590 namespace = str(facts.get("namespace_package", ""))
591 prefix = namespace.replace(".", "-")
592 flat = name.replace("/", "-")
593 package_name = f"{prefix}-{flat}" if prefix else flat
594 data: dict[str, Any] = {
595 **facts,
596 # The forge facts ride the contract: a package's changelog
597 # links its own pull requests on the workspace's forge.
598 **package_injections(root),
599 "package_dir": name,
600 "package_name": package_name,
601 "package_description": default_description(
602 package_name, str(facts.get("project_name", ""))
603 ),
604 }
605 from livery.workshop._seeds import create_package, derived
606
607 data.update(derived(data))
608 create_package(root, destination, template, data, answers)
609 from livery.workshop._shipped_files import deliver
610
611 deliver(root)
612 return str(data["import_path"])