1"""Prose fragments: what the extensions say to the agent and to a reader, in sections.
3An extension's prose, its voice, its standards, its rules, is a set of
4fragments, and one set writes the agent's entry file and the site's
5development pages. A fragment is a markdown file in the extension's
6``content/fragments/`` named ``<section>.<topic>[.<audience>].md``, or
7one the base renders from its registries, a render that takes the
8audience. The base defines the sections and their order, and an
9extension adds fragments to them, never a section. The audience is
10``agent`` or ``human``, and a name without one serves both; a render
11answers each audience itself, and an empty answer leaves the fragment
12out for that reader. A topic is never named ``agent`` or ``human``: the
13last part of a name spells the audience.
15``fm sync`` delivers the agent's set flat under ``.workshop/fragments/``
16with the audience dropped from the name: a shipped fragment byte for
17byte its source, a rendered one under a header naming its origin, each
18through the fragment engine so an edited copy is kept and named. The
19repository's own fragments live in ``fragments/`` at the root under the
20same names, are never copied, and come last. Reach for
21[livery.workshop._prose.fragments][] for the set a reader gets and
22[livery.workshop._shipped_files][] for the delivery.
23"""
41#: The base's sections, in the order the entry file and the site read them.
43 "identity",
44 "voice",
45 "standards",
46 "rules",
47 "workflow",
48 "gate",
49 "verbs",
50 "compositions",
51 "tools",
52)
54#: The fragments directory: an extension's under its content, the repository's
55#: own at the root.
58#: The extension name of the repository's own fragments.
61#: A render: the workspace root and the audience, ``agent``, ``human``
62#: or None for no particular reader, to the markdown; empty leaves the
63#: fragment out for that reader.
68 """A fragment name the guidance refuses; the message names the files."""
73 """One prose fragment: a file an extension ships, or a render from the registries.
75 Attributes:
76 section: The section it belongs to, one of the base's.
77 topic: What it is about; with the section, its name.
78 audience: ``agent`` or ``human`` for a file that serves one
79 reader, empty for both; a rendered fragment is empty here
80 and answers per audience.
81 extension: The extension that ships or renders it; empty for the
82 repository's own.
83 source: The shipped file, or None for a rendered fragment.
84 render: The render, or None for a shipped fragment.
85 """
96 """The delivered file name, ``<section>.<topic>.md``."""
97 return f"{self.section}.{self.topic}.md"
101 """Where it comes from, for a refusal: the posix file, or the extension."""
102 if self.source is not None:102 ↛ 104line 102 didn't jump to line 104 because the condition on line 102 was always true
103 return f"{self.source.as_posix()} ({self.extension or 'this repository'})"
104 return f"the render of {self.extension}"
107 """The markdown for *audience*: the shipped text, or the render's answer."""
108 if self.render is not None:
109 return self.render(root, audience)
110 if self.source is not None:110 ↛ 112line 110 didn't jump to line 112 because the condition on line 110 was always true
111 return self.source.read_text(encoding="utf-8")
112 return ""
116 if section not in BASE_SECTIONS:
117 raise ProseError(
118 f"{where}: section {section!r} is not one of the sections; the"
119 f" sections are {', '.join(BASE_SECTIONS)}"
120 )
124 """Split a fragment file name into section, topic and audience.
126 ``rules.tests.agent.md`` is the rules section, the topic tests, for
127 the agent. A third part spells the audience, so a topic is never
128 named ``agent`` or ``human``. Refuses a name outside the convention
129 and an unknown section, naming *where*, the file by default.
130 """
131 where = where or filename
132 stem, dot, suffix = filename.rpartition(".")
133 parts = stem.split(".") if dot and suffix == "md" else []
134 audience = ""
135 if len(parts) > 2 and parts[-1] in AUDIENCES:
136 audience = parts.pop()
137 if len(parts) != 2 or not all(parts):
138 raise ProseError(
139 f"{where}: a fragment is named <section>.<topic>[.<audience>].md"
140 )
141 section, topic = parts
142 _check_section(where, section)
143 return section, topic, audience
147 """The fragments *extension* ships under ``content/fragments/``, in name order.
149 Every file there is a fragment, so a name outside the convention
150 refuses naming the file. The repository's own come from its root
151 with the empty extension name.
152 """
153 directory = content / OWN
154 if not directory.is_dir():
155 return []
156 found: list[Prose] = []
157 for path in sorted(directory.iterdir()):
158 if not path.is_file():158 ↛ 159line 158 didn't jump to line 159 because the condition on line 158 was never true
159 continue
160 section, topic, audience = parse_name(path.name, where=path.as_posix())
161 found.append(Prose(section, topic, audience, extension, source=path))
162 return found
166 """The repository's own fragments under ``fragments/`` at *root*, in name order."""
167 return shipped(REPOSITORY, root)
171 """Every shipped fragment in play: each extension's set in *order*, then the own.
173 *order* is the mounted extensions' order, the workspace's stack when
174 absent. An extension that ships no content adds nothing.
175 """
176 from livery.workshop._extensions import extension_content, stack_names
178 listed: list[Prose] = []
179 for extension in stack_names(root) if order is None else order:
180 content = extension_content(extension)
181 if content is not None:
182 listed += shipped(extension, content)
183 return [*listed, *repository_fragments(root)]
187 """The guidance one reader gets in the workspace at *root*, in reading order.
189 *audience* is [livery.workshop.AGENT][] or [livery.workshop.HUMAN][].
190 The set is every fragment the mounted extensions ship, every
191 fragment the base renders, and the repository's own under
192 ``fragments/``: by section, then by extension in mount order, the
193 repository's own last, then by name. A fragment written for the
194 other reader is left out.
196 Raises:
197 ValueError: when two fragments in the set deliver under one name,
198 naming both.
199 """
200 return fragments(root, in_play(root), audience)
204 """The extensions the sets of the packages present in *root* hold."""
205 from livery.workshop._composition import extension_set
206 from livery.workshop._packages import discover_packages
208 return frozenset(
209 name for package in discover_packages(root) for name in extension_set(package)
210 )
214 root: Path, shipped: Iterable[Prose], audience: str | None
215) -> list[Prose]:
216 """The fragments *audience* reads: by section, then extension, then name.
218 A shipped fragment for the other reader is left out; a rendered
219 fragment is always in and answers for itself when rendered. The
220 mounted extensions come in mount order, an extension outside the mount
221 after them, and the repository's own last. Two fragments of one
222 name in the set refuse naming both.
223 """
224 from livery.workshop._extensions import stack_names
226 chosen: list[Prose] = []
227 for prose in [*shipped, *_RENDERED.values()]:
228 if prose.audience and prose.audience != audience:
229 continue
230 chosen.append(prose)
231 mounted = list(stack_names(root))
233 def rank(prose: Prose) -> tuple[int, int, int, str, str]:
234 if prose.extension == REPOSITORY:
235 tier, index, name = 2, 0, ""
236 elif prose.extension in mounted:
237 tier, index, name = 0, mounted.index(prose.extension), ""
238 else:
239 tier, index, name = 1, 0, prose.extension
240 return (BASE_SECTIONS.index(prose.section), tier, index, name, prose.name)
242 chosen.sort(key=rank)
243 seen: dict[str, Prose] = {}
244 for prose in chosen:
245 other = seen.setdefault(prose.name, prose)
246 if other is not prose:
247 raise ProseError(
248 f"two fragments deliver as {prose.name}: {other.origin} and"
249 f" {prose.origin}; a topic is unique across everything delivered"
250 )
251 return chosen
255 """The gate's steps for the extensions the members hold.
257 A list for the agent, a table for a reader. A step of a phase the
258 gate does not run, one declared ``gated = false``, is left out.
259 """
260 from livery.workshop._steps import _gated, steps_by_name
262 present = present_extensions(root)
263 records = [
264 record
265 for record in steps_by_name().values()
266 if _gated(record)
267 and (not record.extensions or present & set(record.extensions))
268 ]
269 if not records:269 ↛ 270line 269 didn't jump to line 270 because the condition on line 269 was never true
270 return ""
271 held = ", ".join(sorted(present)) or "none"
272 prog = footman.prog()
273 lines = ["# The gate's steps", ""]
274 if audience == HUMAN:
275 lines += [
276 f"`{prog} check` runs every step below, each registered by an"
277 f" extension; the members hold the extensions {held}.",
278 "",
279 "| step | tools | packages | rewrites under `--fix` |",
280 "| --- | --- | --- | --- |",
281 ]
282 for record in records:
283 tools = ", ".join(record.tools) or "none"
284 scope = " or ".join(record.extensions) or "every"
285 fix = "yes" if record.fix is not None else "no"
286 lines.append(f"| {record.name} | {tools} | {scope} | {fix} |")
287 else:
288 lines += [
289 f"`{prog} check` runs these steps in parallel, the rewriters first"
290 f" and one at a time under `--fix`; the members hold the"
291 f" extensions {held}.",
292 "",
293 ]
294 for record in records:
295 # The name carries the tool; the store's tools are named
296 # only where they are more than it.
297 tools = (
298 f" ({', '.join(record.tools)})"
299 if record.tools and record.tools != (record.step,)
300 else ""
301 )
302 where = "the workspace"
303 if record.extensions:
304 where = f"{' or '.join(record.extensions)} packages"
305 fix = "; rewrites under --fix" if record.fix is not None else ""
306 lines.append(f"- {record.name}{tools}: judges {where}{fix}")
307 return "\n".join(lines) + "\n"
310#: The trees this process listed, by root and the stamps of the tasks
311#: file and the contract: a listing is a runner process, and a sync
312#: renders the verbs fragment for two readers on each of its passes.
317 from livery.workshop._contract import _stamp
319 return (str(root), _stamp(root / "tasks.py"), _stamp(root / "workshop.toml"))
323 """Drop every tree this process listed, so the next read lists again."""
324 _TREES.clear()
328 """This process's own project root, the one tree it holds already."""
329 return footman.project_root()
333 """The workspace's composed task tree, as ``--json --list`` reports it.
335 This process's own workspace answers from the tree it discovered
336 ([livery.footman.task_tree][]). Another root, a newborn a birth syncs
337 from its parent's task, is listed by running the runner there: its
338 tree lives in its own venv's entry points, which only a process in
339 that venv can list. None without a tasks file at the root, without
340 the runner on PATH, and when the listing fails: the fragment is then
341 left out rather than guessed. Listed once per process; a later read
342 answers from the first until the tasks file or the contract changes.
343 """
344 if not (root / "tasks.py").is_file():
345 return None
346 key = _tree_key(root)
347 if key in _TREES:
348 return _TREES[key]
349 own = _own_root()
350 if own is not None and own.resolve() == root.resolve():
351 tree = footman.task_tree()
352 _TREES[key] = tree
353 return tree
354 runner = shutil.which(footman.prog())
355 if runner is None:
356 return None
357 result = footman.run(
358 [runner, "--json", "--list"], cwd=root, nofail=True, recorded=False
359 )
360 if int(result) != 0:360 ↛ 361line 360 didn't jump to line 361 because the condition on line 360 was never true
361 return None
362 tree = cast("dict[str, Any]", json.loads(result.stdout)["tree"])
363 _TREES[key] = tree
364 return tree
368 """The verbs by provider, then what each extension of the installed set provides.
370 The composed tree's verbs open it: the base's, those of each plugin
371 no extension of the set carries, and the repository's own last.
372 Then each extension of the installed set, in composition order, has
373 a block, read from its declaration: what it does, its verbs, its
374 templates, its contract keys and step options, the steps it
375 declares off, and the extensions it cooperates with. Without a
376 tree, as a workspace without a tasks file has, the blocks stand
377 alone; with neither a verb nor an extension, the fragment is left
378 out.
379 """
380 from livery.workshop._capabilities import blocks, render_block, verbs_by_provider
381 from livery.workshop._extensions import stack_names
383 tree = composed_tree(root)
384 found, by_extension = blocks(root, verbs_by_provider(tree) if tree else {})
385 if not found and not by_extension:
386 return ""
387 mounted = [
388 extension for extension in stack_names(root) if extension in by_extension
389 ]
390 others = sorted(
391 extension
392 for extension in by_extension
393 if extension not in mounted and extension != REPOSITORY
394 )
395 ordered = [*mounted, *others, *([REPOSITORY] if REPOSITORY in by_extension else [])]
396 prog = footman.prog()
397 lines = ["# The verbs by extension", ""]
398 if ordered:
399 if audience == HUMAN:
400 lines.append(
401 f"`{prog}` composes these verbs from the base, the plugins the"
402 " project mounts and the repository's own tasks file, and an"
403 f" extension's verbs are in its section below; `{prog} <verb>"
404 " --help` describes one."
405 )
406 else:
407 lines.append(
408 f"Every job goes through `{prog}`; these are its verbs, by what"
409 " provides them: the base, each plugin the project mounts, and"
410 " the repository's own tasks file. An extension's verbs are in"
411 " its block below. Verbs hidden from `--help`, which CI and other"
412 f" verbs call, are not listed; `{prog} --all --help` shows them:"
413 )
414 lines.append("")
415 for extension in ordered:
416 verbs = sorted(verb.address for verb in by_extension[extension])
417 lines.append(f"- {extension or 'this repository'}: {', '.join(verbs)}")
418 lines.append("")
419 if found:
420 lines += [
421 "Each extension the workspace installs, listed or required by one"
422 " listed, has a block below: what it does, its verbs, its templates,"
423 " the contract keys and step options it reads, and the installed"
424 " extensions it contributes to. A package turns any step off with"
425 " `enabled = false` in its `[phases.<phase>.<step>]` table.",
426 "",
427 ]
428 for block in found:
429 lines += render_block(block, audience)
430 return "\n".join(lines).rstrip("\n") + "\n"
434 """The sets of extensions the present packages hold, each with its packages.
436 A set is named by the shortest list that composes it, the extensions
437 joined with ``+``, and is listed with every extension it holds and
438 the gate phases that judge a package holding it. A package holding
439 no extension is listed under ``none``.
440 """
441 from livery.workshop._composition import extension_set, implied
442 from livery.workshop._extensions import installed_declaration
443 from livery.workshop._packages import discover_packages
444 from livery.workshop._phases import declared_phases
445 from livery.workshop._steps import judges_extensions, steps_by_name
447 gated = {name for name, spec in declared_phases().items() if spec.gated}
448 members: dict[tuple[str, ...], list[str]] = {}
449 for package in discover_packages(root):
450 held = extension_set(package)
451 members.setdefault(held, []).append(package.path)
452 if not members:
453 return ""
454 lines = ["# The compositions present", ""]
455 if audience == HUMAN:
456 lines += [
457 "| composition | extensions | packages | gate phases |",
458 "| --- | --- | --- | --- |",
459 ]
460 else:
461 lines += [
462 "The sets of extensions the packages hold, each named by the shortest"
463 " list that composes it, with its packages and the gate phases that"
464 " judge them:",
465 "",
466 ]
467 named: dict[tuple[str, ...], str] = {}
468 for held in members:
469 required = implied(held, installed_declaration)
470 # The shortest list leaves out what another member requires; a
471 # cycle among the requires leaves nothing out of the whole set.
472 shortest = [name for name in held if name not in required] or held
473 named[held] = "+".join(shortest) or "none"
474 for held in sorted(members, key=named.__getitem__):
475 extensions = ", ".join(held) or "none"
476 paths = ", ".join(sorted(members[held]))
477 # A set's phases are those of the gate's steps that judge a
478 # package holding it; a step naming no extensions judges the
479 # workspace, never one set, and a step of a phase the gate never
480 # runs, the docs phase's, is no gate's.
481 phases = (
482 ", ".join(
483 sorted(
484 {
485 r.phase
486 for r in steps_by_name().values()
487 if r.phase in gated
488 and r.extensions
489 and judges_extensions(r, held)
490 }
491 )
492 )
493 or "none"
494 )
495 if audience == HUMAN:
496 lines.append(f"| {named[held]} | {extensions} | {paths} | {phases} |")
497 else:
498 lines.append(
499 f"- {named[held]} ({paths}): holds {extensions}; gate phases {phases}"
500 )
501 return "\n".join(lines) + "\n"
505 """The tools the lock pins, each with its version and the sites requiring it."""
506 from livery.workshop._tools import current_lock, requirements
508 lock = current_lock(root)
509 if lock is None or not lock.tools:
510 return ""
511 sites: dict[str, set[str]] = {}
512 for requirement in requirements(root):
513 sites.setdefault(requirement.name, set()).add(requirement.site)
514 prog = footman.prog()
515 hosts = ", ".join(lock.hosts)
516 lines = ["# The locked tools", ""]
517 if audience == HUMAN:
518 lines.append(
519 f"`toolroom.lock` pins these for {hosts}; `{prog} toolroom.sync` installs"
520 f" them into the tool store, and `{prog} sync` runs it."
521 )
522 else:
523 lines.append(
524 f"The tool store holds these versions, pinned by `toolroom.lock` for"
525 f" {hosts}; `{prog} sync` installs them, never a hand install:"
526 )
527 lines.append("")
528 for name in sorted(lock.tools):
529 where = ", ".join(sorted(sites.get(name, ())))
530 scope = ", ".join(lock.tools[name].on)
531 lines.append(
532 f"- {name} {lock.tools[name].version}"
533 + (f": {where}" if where else "")
534 + (f" ({scope} only)" if scope else "")
535 )
536 return "\n".join(lines) + "\n"
539#: The base's rendered fragments by delivered name: what the registries
540#: say, never written by hand.
542 prose.name: prose
543 for prose in (
544 Prose("gate", "checks", render=render_gate),
545 Prose("verbs", "extensions", render=render_verbs),
546 Prose("compositions", "present", render=render_compositions),
547 Prose("tools", "locked", render=render_tools),
548 )
549}