Prose fragments: what the extensions say to the agent and to a reader, in sections.
An extension's prose, its voice, its standards, its rules, is a set of
fragments, and one set writes the agent's entry file and the site's
development pages. A fragment is a markdown file in the extension's
content/fragments/ named <section>.<topic>[.<audience>].md, or
one the base renders from its registries, a render that takes the
audience. The base defines the sections and their order, and an
extension adds fragments to them, never a section. The audience is
agent or human, and a name without one serves both; a render
answers each audience itself, and an empty answer leaves the fragment
out for that reader. A topic is never named agent or human: the
last part of a name spells the audience.
fm sync delivers the agent's set flat under .workshop/fragments/
with the audience dropped from the name: a shipped fragment byte for
byte its source, a rendered one under a header naming its origin, each
through the fragment engine so an edited copy is kept and named. The
repository's own fragments live in fragments/ at the root under the
same names, are never copied, and come last. Reach for
livery.workshop._prose.fragments for the set a reader gets and
livery.workshop._shipped_files for the delivery.
Classes:
| Name |
Description |
ProseError |
A fragment name the guidance refuses; the message names the files.
|
Prose |
One prose fragment: a file an extension ships, or a render from the registries.
|
Functions:
| Name |
Description |
parse_name |
Split a fragment file name into section, topic and audience.
|
shipped |
The fragments extension ships under content/fragments/, in name order.
|
repository_fragments |
The repository's own fragments under fragments/ at root, in name order.
|
in_play |
Every shipped fragment in play: each extension's set in order, then the own.
|
guidance |
The guidance one reader gets in the workspace at root, in reading order.
|
present_extensions |
The extensions the sets of the packages present in root hold.
|
fragments |
The fragments audience reads: by section, then extension, then name.
|
render_gate |
The gate's steps for the extensions the members hold.
|
forget_trees |
Drop every tree this process listed, so the next read lists again.
|
composed_tree |
The workspace's composed task tree, as --json --list reports it.
|
render_verbs |
The verbs by provider, then what each extension of the installed set provides.
|
render_compositions |
The sets of extensions the present packages hold, each with its packages.
|
render_tools |
The tools the lock pins, each with its version and the sites requiring it.
|
Attributes:
BASE_EXTENSION
module-attribute
BASE_EXTENSION = 'livery.workshop'
AUDIENCES
module-attribute
BASE_SECTIONS
module-attribute
BASE_SECTIONS = ('identity', 'voice', 'standards', 'rules', 'workflow', 'gate', 'verbs', 'compositions', 'tools')
REPOSITORY
module-attribute
ProseError
Bases: ValueError
A fragment name the guidance refuses; the message names the files.
Prose
dataclass
One prose fragment: a file an extension ships, or a render from the registries.
Attributes:
| Name |
Type |
Description |
section |
str
|
The section it belongs to, one of the base's.
|
topic |
str
|
What it is about; with the section, its name.
|
audience |
str
|
agent or human for a file that serves one
reader, empty for both; a rendered fragment is empty here
and answers per audience.
|
extension |
str
|
The extension that ships or renders it; empty for the
repository's own.
|
source |
Path | None
|
The shipped file, or None for a rendered fragment.
|
render |
Render | None
|
The render, or None for a shipped fragment.
|
Methods:
| Name |
Description |
text |
The markdown for audience: the shipped text, or the render's answer.
|
section
instance-attribute
audience
class-attribute
instance-attribute
extension
class-attribute
instance-attribute
source
class-attribute
instance-attribute
source: Path | None = None
render
class-attribute
instance-attribute
name
property
The delivered file name, <section>.<topic>.md.
origin
property
Where it comes from, for a refusal: the posix file, or the extension.
text
The markdown for audience: the shipped text, or the render's answer.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def text(self, root: Path, audience: str | None) -> str:
"""The markdown for *audience*: the shipped text, or the render's answer."""
if self.render is not None:
return self.render(root, audience)
if self.source is not None:
return self.source.read_text(encoding="utf-8")
return ""
|
parse_name
Split a fragment file name into section, topic and audience.
rules.tests.agent.md is the rules section, the topic tests, for
the agent. A third part spells the audience, so a topic is never
named agent or human. Refuses a name outside the convention
and an unknown section, naming where, the file by default.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def parse_name(filename: str, *, where: str = "") -> tuple[str, str, str]:
"""Split a fragment file name into section, topic and audience.
``rules.tests.agent.md`` is the rules section, the topic tests, for
the agent. A third part spells the audience, so a topic is never
named ``agent`` or ``human``. Refuses a name outside the convention
and an unknown section, naming *where*, the file by default.
"""
where = where or filename
stem, dot, suffix = filename.rpartition(".")
parts = stem.split(".") if dot and suffix == "md" else []
audience = ""
if len(parts) > 2 and parts[-1] in AUDIENCES:
audience = parts.pop()
if len(parts) != 2 or not all(parts):
raise ProseError(
f"{where}: a fragment is named <section>.<topic>[.<audience>].md"
)
section, topic = parts
_check_section(where, section)
return section, topic, audience
|
shipped
The fragments extension ships under content/fragments/, in name order.
Every file there is a fragment, so a name outside the convention
refuses naming the file. The repository's own come from its root
with the empty extension name.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def shipped(extension: str, content: Path) -> list[Prose]:
"""The fragments *extension* ships under ``content/fragments/``, in name order.
Every file there is a fragment, so a name outside the convention
refuses naming the file. The repository's own come from its root
with the empty extension name.
"""
directory = content / OWN
if not directory.is_dir():
return []
found: list[Prose] = []
for path in sorted(directory.iterdir()):
if not path.is_file():
continue
section, topic, audience = parse_name(path.name, where=path.as_posix())
found.append(Prose(section, topic, audience, extension, source=path))
return found
|
repository_fragments
The repository's own fragments under fragments/ at root, in name order.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def repository_fragments(root: Path) -> list[Prose]:
"""The repository's own fragments under ``fragments/`` at *root*, in name order."""
return shipped(REPOSITORY, root)
|
in_play
Every shipped fragment in play: each extension's set in order, then the own.
order is the mounted extensions' order, the workspace's stack when
absent. An extension that ships no content adds nothing.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def in_play(root: Path, order: Iterable[str] | None = None) -> list[Prose]:
"""Every shipped fragment in play: each extension's set in *order*, then the own.
*order* is the mounted extensions' order, the workspace's stack when
absent. An extension that ships no content adds nothing.
"""
from livery.workshop._extensions import extension_content, stack_names
listed: list[Prose] = []
for extension in stack_names(root) if order is None else order:
content = extension_content(extension)
if content is not None:
listed += shipped(extension, content)
return [*listed, *repository_fragments(root)]
|
guidance
The guidance one reader gets in the workspace at root, in reading order.
audience is livery.workshop.AGENT or livery.workshop.HUMAN.
The set is every fragment the mounted extensions ship, every
fragment the base renders, and the repository's own under
fragments/: by section, then by extension in mount order, the
repository's own last, then by name. A fragment written for the
other reader is left out.
Raises:
| Type |
Description |
ValueError
|
when two fragments in the set deliver under one name,
naming both.
|
Source code in packages/workshop/src/livery/workshop/_prose.py
| def guidance(root: Path, audience: str) -> list[Prose]:
"""The guidance one reader gets in the workspace at *root*, in reading order.
*audience* is [livery.workshop.AGENT][] or [livery.workshop.HUMAN][].
The set is every fragment the mounted extensions ship, every
fragment the base renders, and the repository's own under
``fragments/``: by section, then by extension in mount order, the
repository's own last, then by name. A fragment written for the
other reader is left out.
Raises:
ValueError: when two fragments in the set deliver under one name,
naming both.
"""
return fragments(root, in_play(root), audience)
|
present_extensions
The extensions the sets of the packages present in root hold.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def present_extensions(root: Path) -> frozenset[str]:
"""The extensions the sets of the packages present in *root* hold."""
from livery.workshop._composition import extension_set
from livery.workshop._packages import discover_packages
return frozenset(
name for package in discover_packages(root) for name in extension_set(package)
)
|
fragments
The fragments audience reads: by section, then extension, then name.
A shipped fragment for the other reader is left out; a rendered
fragment is always in and answers for itself when rendered. The
mounted extensions come in mount order, an extension outside the mount
after them, and the repository's own last. Two fragments of one
name in the set refuse naming both.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def fragments(
root: Path, shipped: Iterable[Prose], audience: str | None
) -> list[Prose]:
"""The fragments *audience* reads: by section, then extension, then name.
A shipped fragment for the other reader is left out; a rendered
fragment is always in and answers for itself when rendered. The
mounted extensions come in mount order, an extension outside the mount
after them, and the repository's own last. Two fragments of one
name in the set refuse naming both.
"""
from livery.workshop._extensions import stack_names
chosen: list[Prose] = []
for prose in [*shipped, *_RENDERED.values()]:
if prose.audience and prose.audience != audience:
continue
chosen.append(prose)
mounted = list(stack_names(root))
def rank(prose: Prose) -> tuple[int, int, int, str, str]:
if prose.extension == REPOSITORY:
tier, index, name = 2, 0, ""
elif prose.extension in mounted:
tier, index, name = 0, mounted.index(prose.extension), ""
else:
tier, index, name = 1, 0, prose.extension
return (BASE_SECTIONS.index(prose.section), tier, index, name, prose.name)
chosen.sort(key=rank)
seen: dict[str, Prose] = {}
for prose in chosen:
other = seen.setdefault(prose.name, prose)
if other is not prose:
raise ProseError(
f"two fragments deliver as {prose.name}: {other.origin} and"
f" {prose.origin}; a topic is unique across everything delivered"
)
return chosen
|
render_gate
render_gate(root: Path, audience: str | None) -> str
The gate's steps for the extensions the members hold.
A list for the agent, a table for a reader. A step of a phase the
gate does not run, one declared gated = false, is left out.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def render_gate(root: Path, audience: str | None) -> str:
"""The gate's steps for the extensions the members hold.
A list for the agent, a table for a reader. A step of a phase the
gate does not run, one declared ``gated = false``, is left out.
"""
from livery.workshop._steps import _gated, steps_by_name
present = present_extensions(root)
records = [
record
for record in steps_by_name().values()
if _gated(record)
and (not record.extensions or present & set(record.extensions))
]
if not records:
return ""
held = ", ".join(sorted(present)) or "none"
prog = footman.prog()
lines = ["# The gate's steps", ""]
if audience == HUMAN:
lines += [
f"`{prog} check` runs every step below, each registered by an"
f" extension; the members hold the extensions {held}.",
"",
"| step | tools | packages | rewrites under `--fix` |",
"| --- | --- | --- | --- |",
]
for record in records:
tools = ", ".join(record.tools) or "none"
scope = " or ".join(record.extensions) or "every"
fix = "yes" if record.fix is not None else "no"
lines.append(f"| {record.name} | {tools} | {scope} | {fix} |")
else:
lines += [
f"`{prog} check` runs these steps in parallel, the rewriters first"
f" and one at a time under `--fix`; the members hold the"
f" extensions {held}.",
"",
]
for record in records:
# The name carries the tool; the store's tools are named
# only where they are more than it.
tools = (
f" ({', '.join(record.tools)})"
if record.tools and record.tools != (record.step,)
else ""
)
where = "the workspace"
if record.extensions:
where = f"{' or '.join(record.extensions)} packages"
fix = "; rewrites under --fix" if record.fix is not None else ""
lines.append(f"- {record.name}{tools}: judges {where}{fix}")
return "\n".join(lines) + "\n"
|
forget_trees
Drop every tree this process listed, so the next read lists again.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def forget_trees() -> None:
"""Drop every tree this process listed, so the next read lists again."""
_TREES.clear()
|
composed_tree
The workspace's composed task tree, as --json --list reports it.
This process's own workspace answers from the tree it discovered
(livery.footman.task_tree). Another root, a newborn a birth syncs
from its parent's task, is listed by running the runner there: its
tree lives in its own venv's entry points, which only a process in
that venv can list. None without a tasks file at the root, without
the runner on PATH, and when the listing fails: the fragment is then
left out rather than guessed. Listed once per process; a later read
answers from the first until the tasks file or the contract changes.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def composed_tree(root: Path) -> dict[str, Any] | None:
"""The workspace's composed task tree, as ``--json --list`` reports it.
This process's own workspace answers from the tree it discovered
([livery.footman.task_tree][]). Another root, a newborn a birth syncs
from its parent's task, is listed by running the runner there: its
tree lives in its own venv's entry points, which only a process in
that venv can list. None without a tasks file at the root, without
the runner on PATH, and when the listing fails: the fragment is then
left out rather than guessed. Listed once per process; a later read
answers from the first until the tasks file or the contract changes.
"""
if not (root / "tasks.py").is_file():
return None
key = _tree_key(root)
if key in _TREES:
return _TREES[key]
own = _own_root()
if own is not None and own.resolve() == root.resolve():
tree = footman.task_tree()
_TREES[key] = tree
return tree
runner = shutil.which(footman.prog())
if runner is None:
return None
result = footman.run(
[runner, "--json", "--list"], cwd=root, nofail=True, recorded=False
)
if int(result) != 0:
return None
tree = cast("dict[str, Any]", json.loads(result.stdout)["tree"])
_TREES[key] = tree
return tree
|
render_verbs
render_verbs(root: Path, audience: str | None) -> str
The verbs by provider, then what each extension of the installed set provides.
The composed tree's verbs open it: the base's, those of each plugin
no extension of the set carries, and the repository's own last.
Then each extension of the installed set, in composition order, has
a block, read from its declaration: what it does, its verbs, its
templates, its contract keys and step options, the steps it
declares off, and the extensions it cooperates with. Without a
tree, as a workspace without a tasks file has, the blocks stand
alone; with neither a verb nor an extension, the fragment is left
out.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def render_verbs(root: Path, audience: str | None) -> str:
"""The verbs by provider, then what each extension of the installed set provides.
The composed tree's verbs open it: the base's, those of each plugin
no extension of the set carries, and the repository's own last.
Then each extension of the installed set, in composition order, has
a block, read from its declaration: what it does, its verbs, its
templates, its contract keys and step options, the steps it
declares off, and the extensions it cooperates with. Without a
tree, as a workspace without a tasks file has, the blocks stand
alone; with neither a verb nor an extension, the fragment is left
out.
"""
from livery.workshop._capabilities import blocks, render_block, verbs_by_provider
from livery.workshop._extensions import stack_names
tree = composed_tree(root)
found, by_extension = blocks(root, verbs_by_provider(tree) if tree else {})
if not found and not by_extension:
return ""
mounted = [
extension for extension in stack_names(root) if extension in by_extension
]
others = sorted(
extension
for extension in by_extension
if extension not in mounted and extension != REPOSITORY
)
ordered = [*mounted, *others, *([REPOSITORY] if REPOSITORY in by_extension else [])]
prog = footman.prog()
lines = ["# The verbs by extension", ""]
if ordered:
if audience == HUMAN:
lines.append(
f"`{prog}` composes these verbs from the base, the plugins the"
" project mounts and the repository's own tasks file, and an"
f" extension's verbs are in its section below; `{prog} <verb>"
" --help` describes one."
)
else:
lines.append(
f"Every job goes through `{prog}`; these are its verbs, by what"
" provides them: the base, each plugin the project mounts, and"
" the repository's own tasks file. An extension's verbs are in"
" its block below. Verbs hidden from `--help`, which CI and other"
f" verbs call, are not listed; `{prog} --all --help` shows them:"
)
lines.append("")
for extension in ordered:
verbs = sorted(verb.address for verb in by_extension[extension])
lines.append(f"- {extension or 'this repository'}: {', '.join(verbs)}")
lines.append("")
if found:
lines += [
"Each extension the workspace installs, listed or required by one"
" listed, has a block below: what it does, its verbs, its templates,"
" the contract keys and step options it reads, and the installed"
" extensions it contributes to. A package turns any step off with"
" `enabled = false` in its `[phases.<phase>.<step>]` table.",
"",
]
for block in found:
lines += render_block(block, audience)
return "\n".join(lines).rstrip("\n") + "\n"
|
render_compositions
render_compositions(root: Path, audience: str | None) -> str
The sets of extensions the present packages hold, each with its packages.
A set is named by the shortest list that composes it, the extensions
joined with +, and is listed with every extension it holds and
the gate phases that judge a package holding it. A package holding
no extension is listed under none.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def render_compositions(root: Path, audience: str | None) -> str:
"""The sets of extensions the present packages hold, each with its packages.
A set is named by the shortest list that composes it, the extensions
joined with ``+``, and is listed with every extension it holds and
the gate phases that judge a package holding it. A package holding
no extension is listed under ``none``.
"""
from livery.workshop._composition import extension_set, implied
from livery.workshop._extensions import installed_declaration
from livery.workshop._packages import discover_packages
from livery.workshop._phases import declared_phases
from livery.workshop._steps import judges_extensions, steps_by_name
gated = {name for name, spec in declared_phases().items() if spec.gated}
members: dict[tuple[str, ...], list[str]] = {}
for package in discover_packages(root):
held = extension_set(package)
members.setdefault(held, []).append(package.path)
if not members:
return ""
lines = ["# The compositions present", ""]
if audience == HUMAN:
lines += [
"| composition | extensions | packages | gate phases |",
"| --- | --- | --- | --- |",
]
else:
lines += [
"The sets of extensions the packages hold, each named by the shortest"
" list that composes it, with its packages and the gate phases that"
" judge them:",
"",
]
named: dict[tuple[str, ...], str] = {}
for held in members:
required = implied(held, installed_declaration)
# The shortest list leaves out what another member requires; a
# cycle among the requires leaves nothing out of the whole set.
shortest = [name for name in held if name not in required] or held
named[held] = "+".join(shortest) or "none"
for held in sorted(members, key=named.__getitem__):
extensions = ", ".join(held) or "none"
paths = ", ".join(sorted(members[held]))
# A set's phases are those of the gate's steps that judge a
# package holding it; a step naming no extensions judges the
# workspace, never one set, and a step of a phase the gate never
# runs, the docs phase's, is no gate's.
phases = (
", ".join(
sorted(
{
r.phase
for r in steps_by_name().values()
if r.phase in gated
and r.extensions
and judges_extensions(r, held)
}
)
)
or "none"
)
if audience == HUMAN:
lines.append(f"| {named[held]} | {extensions} | {paths} | {phases} |")
else:
lines.append(
f"- {named[held]} ({paths}): holds {extensions}; gate phases {phases}"
)
return "\n".join(lines) + "\n"
|
render_tools(root: Path, audience: str | None) -> str
The tools the lock pins, each with its version and the sites requiring it.
Source code in packages/workshop/src/livery/workshop/_prose.py
| def render_tools(root: Path, audience: str | None) -> str:
"""The tools the lock pins, each with its version and the sites requiring it."""
from livery.workshop._tools import current_lock, requirements
lock = current_lock(root)
if lock is None or not lock.tools:
return ""
sites: dict[str, set[str]] = {}
for requirement in requirements(root):
sites.setdefault(requirement.name, set()).add(requirement.site)
prog = footman.prog()
hosts = ", ".join(lock.hosts)
lines = ["# The locked tools", ""]
if audience == HUMAN:
lines.append(
f"`toolroom.lock` pins these for {hosts}; `{prog} toolroom.sync` installs"
f" them into the tool store, and `{prog} sync` runs it."
)
else:
lines.append(
f"The tool store holds these versions, pinned by `toolroom.lock` for"
f" {hosts}; `{prog} sync` installs them, never a hand install:"
)
lines.append("")
for name in sorted(lock.tools):
where = ", ".join(sorted(sites.get(name, ())))
scope = ", ".join(lock.tools[name].on)
lines.append(
f"- {name} {lock.tools[name].version}"
+ (f": {where}" if where else "")
+ (f" ({scope} only)" if scope else "")
)
return "\n".join(lines) + "\n"
|