1"""The workspace's generated files: the drift check, the writer, new members.
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.
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"""
31 stack_entries,
32 workspace_root,
33)
38 from livery.workshop._declaration import DeclaredTemplate, TemplateOption
40#: What ``fm new`` does, and what ``fm new.package`` does.
46#: The group of the templates' verbs: ``fm new.package.<template>``.
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
59 """The distribution a requirement spec names, extras and floors cut."""
60 return re.split(r"[\[<>=!~; ]", spec.strip(), maxsplit=1)[0]
64 """The contract's python registry, as render inputs.
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}
85 """The render-time values no answer stores.
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
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
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.
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))
145 """The step records' fragments composed per rendered file over *data*."""
146 from livery.workshop._fragments import compose_project
148 return compose_project(fragment_data(data))
152 """*data* with what the step records' fragments read beside it.
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
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 }
178 """The render-time values a package render takes from the contract.
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 {}
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 }
198 """The bytes with LF endings, whatever the platform wrote.
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")
208 """The drift report: generated files (CI, codeowners) that disagree with *root*.
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
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
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
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
244 """The [release] baseline a package's contract declares, or empty.
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", ""))
259 """Write the composed and generated files over *root*; the files that changed.
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
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
282 """Write the emitted artifacts (CI files, codeowners); what changed.
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
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
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
308 for path in retired_files(root):
309 path.unlink()
310 changed.append(f"{path.relative_to(root).as_posix()} (retired)")
311 return changed
315 """Fail when a composed or generated file drifts from what writes it.
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
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 )
339#: The package's name, which every template's verb takes first. Module
340#: level, where footman reads a task's annotations.
343#: Each verb the generator made, to what it was made from: the template
344#: and the options its verb offers.
346 Callable[..., None], tuple[DeclaredTemplate, tuple[TemplateOption, ...]]
347] = weakref.WeakKeyDictionary()
351 templates: Mapping[str, DeclaredTemplate], into: Group | None = None
352) -> None:
353 """Make a verb per template, ``fm new.package.<template>``, from *templates*.
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.
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
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))
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
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))
407 template: DeclaredTemplate, options: Sequence[TemplateOption]
408) -> Callable[..., None]:
409 """The verb that creates a package from *template*, offering *options*."""
410 born = template.name
412 def verb(name: str, **answers: object) -> None:
413 _create(born, name, answers)
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
431 """*option* as a keyword option of its template's verb."""
432 from livery.workshop._declaration import OPTION_TYPES
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 )
447 """The help of *template*'s verb: its doc first, then what a creation does.
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
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))
482 """Create ``packages/<name>`` from *template* with *answers*, then wire it.
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)
504 """Wire the package under packages/<name> into the workspace.
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)
518 """Wire the package under ``packages/<name>`` into *root*.
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.
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
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")
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 )
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.
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
607 data.update(derived(data))
608 create_package(root, destination, template, data, answers)
609 from livery.workshop._shipped_files import deliver
611 deliver(root)
612 return str(data["import_path"])