livery.workshop._graph¶
livery.workshop._graph ¶
The affected engine: which packages a change can influence.
The workspace graph is the [[depends]] edges the contracts
declare. A changed file maps to the package whose directory holds it,
and the affected set is that package plus everything that depends on
it, transitively (the dependents' closure): a change can break its
consumers, never its dependencies. A change outside every package,
the root configuration, the templates, the workspace tests, affects
everything, because the root files configure every gate. A change
can reach further than its package's dependents: a listed extension
says how far through the reaches query, as python does for a
module pytest loads as a plugin into every suite it runs.
fm graph.affected prints the verdict; the quality family's
the reflex and the CI legs scope work to it.
Classes:
| Name | Description |
|---|---|
Scope |
What a change reaches: the packages, and the tests that stand for some. |
Functions:
| Name | Description |
|---|---|
dependents_closure |
seeds (package paths) plus everything depending on them. |
dependencies_closure |
seeds (package paths) plus everything they depend on, transitively. |
reaches_no_package |
Whether path is a root file no package's steps read. |
is_site |
Whether path is the site's own: the root |
is_prose |
Whether path is prose: under |
affected_packages |
The packages this branch's changes can influence, and the workspace's own tests. |
affected_by |
What paths, changed since before, reach among the workspace's packages. |
docs_page |
The package whose authored docs page path is, or None for any other path. |
affected_from_paths |
What a change to paths reaches: the packages, and the tests that stand alone. |
graph_affected |
Print the affected packages for this branch, one per line. |
order_topologically |
packages in release order: every dependency before its dependents. |
Attributes:
| Name | Type | Description |
|---|---|---|
graph |
|
|
NOTES |
|
|
SITE_CONFIG |
|
|
SITE_DOCS |
|
|
NO_PACKAGE |
|
NO_PACKAGE
module-attribute
¶
NO_PACKAGE = ('LICENSE', '.github/**', '.gitea/**', '.gitlab/**', '.gitlab-ci.yml', 'CODEOWNERS', 'docs/CODEOWNERS', '.vscode/**', '.claude/**', '.gitattributes', '.gitignore', 'setup.sh', '.release-manifest.json', 'overrides/**', '.workshop-rendered')
Scope
dataclass
¶
Scope(packages: tuple[Package, ...], tests: Mapping[str, tuple[str, ...]] = dict(), examples: tuple[str, ...] = ())
What a change reaches: the packages, and the tests that stand for some.
Attributes:
| Name | Type | Description |
|---|---|---|
packages |
tuple[Package, ...]
|
The packages to gate, in discovery order, the workspace's own tests unit last when its files changed. |
tests |
Mapping[str, tuple[str, ...]]
|
Per package, the test files that stand for its suite; the walk names none until a better narrowing exists, so every package runs its suite whole. |
examples |
tuple[str, ...]
|
The package paths whose changed files are examples and nothing else: their examples run and no suite. A package reached through its source runs both. |
dependents_closure ¶
seeds (package paths) plus everything depending on them.
Follows the reversed [[depends]] edges to a fixed point, and
answers in discovery order so output stays deterministic.
Source code in packages/workshop/src/livery/workshop/_graph.py
dependencies_closure ¶
seeds (package paths) plus everything they depend on, transitively.
Follows the [[depends]] edges to a fixed point, and answers in
discovery order; livery.workshop.order_topologically
puts each dependency before its dependents.
Source code in packages/workshop/src/livery/workshop/_graph.py
reaches_no_package ¶
Whether path is a root file no package's steps read.
A change to one gates no package; the workspace steps that read it still judge it (livery.workshop._steps.selected).
Source code in packages/workshop/src/livery/workshop/_graph.py
is_site ¶
Whether path is the site's own: the root zensical.toml or docs/ tree.
Only the site build reads them, and it runs on every run, so
they reach no format, lint, type, or test gate. A package's
docs/ directory is the package's, not the site's.
Source code in packages/workshop/src/livery/workshop/_graph.py
is_prose ¶
Whether path is prose: under notes/, or a markdown file anywhere.
Prose reaches no format, lint, type, or test gate. The site build is where markdown is judged, and it runs on every run.
Source code in packages/workshop/src/livery/workshop/_graph.py
affected_packages ¶
The packages this branch's changes can influence, and the workspace's own tests.
None means everything: a touched file outside every package (the
root configuration, templates) configures every gate, so no
narrowing is honest, and the file is named. Prose (is_prose)
and the site's own files (is_site) affect no package wherever
they live, so a diff confined to them affects nothing. A change
under the workspace's own tests/ affects that unit alone,
which the answer then carries as a package of its own
(livery.workshop.workspace_suite): its tests
reach every package, and every leg that runs a suite runs them
anyway, so no package's suite has to run for it. An empty tuple
means the branch changes nothing a gate reads.
Source code in packages/workshop/src/livery/workshop/_graph.py
affected_by ¶
What paths, changed since before, reach among the workspace's packages.
affected_from_paths over the packages discovered under root.
None means everything.
Source code in packages/workshop/src/livery/workshop/_graph.py
docs_page ¶
The package whose authored docs page path is, or None for any other path.
Source code in packages/workshop/src/livery/workshop/_graph.py
affected_from_paths ¶
affected_from_paths(root: Path, packages: tuple[Package, ...], paths: Iterable[str], *, before: str | Callable[[], str] = '') -> Scope | None
What a change to paths reaches: the packages, and the tests that stand alone.
The classification affected_packages applies to a branch's
changes, for any set of paths: the reflex hands it the paths
between a proved tree and the working tree. Each path is
classified by its package's kind: a test file reaches its own
package alone, since nothing imports a test, and that package
runs its whole suite; source, test support, and configuration
reach the package's dependents and run the suites. A change under
the workspace's own tests runs that unit whole. A docs page
reaches nothing: the site build reads it. An example file reaches
its package's examples step
and no suite, unless source of the package changed too. A file
outside every package reaches everything, unless before (the
commit or tree the paths were taken from) shows the change is
about the packages added or removed, or, for uv.lock, about
the members whose resolution it moves
(livery.workshop._root_attribution): then it reaches those.
A change inside a package reaches further when a listed extension
says so: each answer to the reaches query is called with the
change, and every member it names for a changed path runs with
its dependents (_reached).
before may be a function answering it, asked once, and only
when a path outside every package or an answer to reaches
needs it.
None means everything, an empty scope nothing a gate reads.
Source code in packages/workshop/src/livery/workshop/_graph.py
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 | |
graph_affected ¶
graph_affected(base: str = 'main') -> None
Print the affected packages for this branch, one per line.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base
|
str
|
the branch the change will merge into |
'main'
|
Source code in packages/workshop/src/livery/workshop/_graph.py
order_topologically ¶
packages in release order: every dependency before its dependents.
Kahn's walk over the [[depends]] edges restricted to the given
set; ties keep the input order so the result is deterministic. A
cycle cannot arise, the layering lint refuses one long before a
release asks.