Coverage for packages/workshop/src/livery/workshop/_provenance.py: 83%

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"""Provenance: which channel owns a file, and where to edit it.
2
3One classifier answers for any path; everything else serialises its
4answer. ``fm explain <path>`` prints it. The fragment engine and the
5emitters open every file they write with a header, so the answer rides
6the file wherever comments are possible. Materialised copies are never injected:
7override detection depends on the copy staying byte-identical to
8its source, so those files, and comment-hostile ones, are explain's
9territory alone. Shipped extension content carries its header through
10the provenance lint, whose ``--fix`` writes the computed text.
11"""
12
13from __future__ import annotations
14
15import os
16from pathlib import Path
17from typing import Annotated
18
19import livery.footman as footman
20from livery import git
21from livery.footman import Arg, ask, doc, fail, suggest, task
22from livery.workshop._categories import (
23 ChannelRule,
24 Provenance,
25 category_of,
26 channel_of,
27 register_channels,
28)
29from livery.workshop._extensions import SELF, workspace_root
30from livery.workshop._packages import Package
31
32#: Comment leaders by suffix, and by exact name for suffixless files.
33#: A type absent from both tables cannot carry a header and is
34#: explain's territory alone.
35_BY_SUFFIX = {
36 ".py": "#",
37 ".toml": "#",
38 ".yml": "#",
39 ".yaml": "#",
40 ".sh": "#",
41 ".cfg": "#",
42 ".ini": "#",
43 ".md": "html",
44}
45_BY_NAME = {".gitignore": "#", ".gitattributes": "#", "CODEOWNERS": "#"}
46
47
48def comment_style(path: Path) -> str:
49 """The comment leader for *path*: ``#``, ``//``, ``html``, or empty.
50
51 The editor's ``.vscode/settings.json`` is JSON with comments, the
52 one JSON the render owns; every other JSON carries no header.
53 """
54 if path.name == "settings.json" and path.parent.name == ".vscode":
55 return "//"
56 return _BY_NAME.get(path.name, _BY_SUFFIX.get(path.suffix, ""))
57
58
59#: Phrases that mark a header as machine-written, for refresh.
60_MARKERS = (
61 "the workshop from workshop.toml",
62 "Seeded from",
63 "extension content",
64)
65
66
67def format_header(lines: tuple[str, ...], style: str) -> str:
68 """The header *lines* as one comment block in *style*."""
69 if style == "html":
70 body = "".join(f" {line}\n" for line in lines[1:])
71 return f"<!-- {lines[0]}\n{body}-->\n"
72 return "".join(f"{style} {line}\n" for line in lines)
73
74
75def generated_header(style: str, lines: tuple[str, ...] = ()) -> str:
76 """The provenance header a generated file opens with, as a comment block.
77
78 *style* is the file's comment marker (``#`` or ``//``), or ``html``
79 for a ``<!-- -->`` block. *lines* say what writes the file and how
80 a reader changes it, for a file an extension writes outside the
81 engine; without them, the header says what every artifact the
82 engine emits says: the contract is the source, and an edit here is
83 drift.
84 """
85 if not lines:
86 prog = footman.prog()
87 lines = (
88 "Generated by the workshop from workshop.toml; the gate keeps",
89 "it matching. Edit the contract (or the emitters) and run",
90 f"`{prog} sync`; an edit here is drift.",
91 )
92 return format_header(lines, style)
93
94
95def content_header(extension: str, style: str) -> str:
96 """The header shipped extension content carries, lint-enforced."""
97 lines = (
98 f"Shipped as {extension} extension content, delivered to the workspace",
99 "by the sync verb. Edit this copy in the extension and release it;",
100 "an edited delivered copy is a local override, kept and named.",
101 )
102 return format_header(lines, style)
103
104
105def _insertion_point(text: str, path: Path) -> int:
106 """Where a header lands: after a shebang or markdown frontmatter."""
107 if text.startswith("#!"):
108 return text.find("\n") + 1
109 if path.suffix == ".md" and text.startswith("---\n"):
110 end = text.find("\n---\n", 4)
111 if end != -1:111 ↛ 113line 111 didn't jump to line 113 because the condition on line 111 was always true
112 return end + len("\n---\n")
113 return 0
114
115
116def inject(path: Path, header: str) -> None:
117 """Open *path* with *header*, replacing a stale machine header."""
118 text = path.read_text(encoding="utf-8")
119 text = strip_header(text, path, size=len(header.splitlines()))
120 at = _insertion_point(text, path)
121 path.write_text(text[:at] + header + text[at:], encoding="utf-8", newline="\n")
122
123
124def has_header(path: Path, header: str) -> bool:
125 """Whether *path* already opens with *header* (shebang-tolerant)."""
126 text = path.read_text(encoding="utf-8")
127 at = _insertion_point(text, path)
128 return text[at:].startswith(header)
129
130
131def strip_header(text: str, path: Path, *, size: int = 3) -> str:
132 """*text* with a machine-written header removed, everything after it kept.
133
134 An HTML header is its ``<!-- -->`` block. A line-comment header is
135 its first *size* lines, the length every machine header is written
136 at, when the first carries a marker: the comment lines below it are
137 the file's own and stay, and so does a blank line after either.
138 """
139 at = _insertion_point(text, path)
140 head, tail = text[:at], text[at:]
141 style = comment_style(path)
142 if style == "html":
143 if tail.startswith("<!--") and "-->" in tail:
144 block, _, rest = tail.partition("-->\n")
145 if any(marker in block for marker in _MARKERS):145 ↛ 147line 145 didn't jump to line 147 because the condition on line 145 was always true
146 return head + rest
147 return text
148 lines = tail.splitlines(keepends=True)
149 first = lines[:size]
150 leader = style or "#"
151 if (
152 len(first) == size
153 and all(line.startswith(leader) for line in first)
154 and any(marker in first[0] for marker in _MARKERS)
155 ):
156 return head + "".join(lines[size:])
157 return text
158
159
160def _materialised(root: Path, relative: Path) -> Provenance | None:
161 """The answer for a path under ``.workshop/``, this checkout's state, or None."""
162 del root
163 prog = footman.prog()
164 parts = relative.parts
165 if parts[0] == ".workshop":
166 if parts[1:2] == ("fragments",):
167 return Provenance(
168 "extension fragment",
169 f"a mounted extension's content/fragments/{relative.name}, or a"
170 " render from its registries",
171 f"edit the extension's copy; an edit here is a local override"
172 f" `{prog} sync` keeps and names",
173 )
174 # Everything else under .workshop is this checkout's own: the
175 # tool receipts, the stub receipt, the linked binaries. None of
176 # them has an edit path, and
177 # calling them extension fragments was a lie the directory's older
178 # shape made easy to tell.
179 return Provenance(
180 "checkout state",
181 f"written by `{prog} sync` for this checkout alone",
182 "nothing to edit here; delete it and the next sync writes it again",
183 )
184 return None
185
186
187def _computed(root: Path, relative: Path) -> Provenance | None:
188 """The answer for a file a listed extension's code writes, or None.
189
190 A path under a directory such a render writes, which the render did
191 not write, is the repository's own: the agent's own skill beside the
192 delivered ones, say.
193 """
194 from livery.workshop._extensions import declaration
195 from livery.workshop._fragment_engine import local_receipts
196 from livery.workshop._shipped_files import delivery_order
197
198 prog = footman.prog()
199 path = relative.as_posix()
200 for extension in delivery_order(root):
201 found = None if extension == SELF else declaration(extension)
202 for fragment in found.fragments if found is not None else ():
203 target = fragment.target
204 if path != target and not (
205 target.endswith("/") and path.startswith(target)
206 ):
207 continue
208 where = f"`{prog} sync`, from {extension}'s [fragments] render for {target}"
209 if not fragment.local:209 ↛ 218line 209 didn't jump to line 218 because the condition on line 209 was always true
210 return Provenance(
211 "computed",
212 where,
213 f"change what it is computed from and run `{prog} sync`;"
214 " an edit here is drift",
215 )
216 # A linked directory's files are the link's: the receipt
217 # names the link, the nearest written ancestor.
218 receipts = local_receipts(root)
219 ancestors = [path, *(parent.as_posix() for parent in relative.parents)]
220 if any(candidate in receipts for candidate in ancestors):
221 return Provenance(
222 "materialised",
223 where,
224 "edit what it is computed from; an edit here is a local"
225 f" override `{prog} sync` keeps and names",
226 )
227 return Provenance(
228 "yours",
229 "this repository",
230 "edit directly; it commits like any repo file",
231 )
232 return None
233
234
235def emitted_paths(root: Path) -> frozenset[str]:
236 """The paths the workshop emitters write for *root*, the owners file included.
237
238 One emission is a full render of every workflow, the site
239 configuration, and the entry script; a caller classifying many
240 paths computes this once and hands it to
241 [livery.workshop._provenance.classify][].
242 """
243 from livery.workshop._ci_generate import generate
244 from livery.workshop._governance import codeowners_file
245
246 generated = set(generate(root))
247 owners = codeowners_file(root)
248 if owners is not None:248 ↛ 250line 248 didn't jump to line 250 because the condition on line 248 was always true
249 generated.add(owners.path)
250 return frozenset(generated)
251
252
253def classify(
254 root: Path, relative: Path, *, emitted: frozenset[str] | None = None
255) -> Provenance:
256 """The provenance of *relative* inside *root*; "yours" when no channel claims it.
257
258 *relative* is taken lexically, never resolved: a materialised
259 link classifies as the delivered entry it is, not as the wheel
260 path it points into. *emitted* is the emitters' path set from
261 [livery.workshop._provenance.emitted_paths][]; a caller with many
262 paths passes one set rather than paying an emission per path.
263 The answer comes from the channel registry, the builtin ladder
264 below and whatever an extension registered beside it, highest rank
265 first.
266 """
267 found = channel_of(root, relative, emitted=emitted)
268 if found is not None:
269 return found.provenance
270 return Provenance("yours", "this repository", "edit directly")
271
272
273def _rule_materialised(
274 root: Path, relative: Path, emitted: frozenset[str] | None
275) -> Provenance | None:
276 del emitted
277 return _materialised(root, relative)
278
279
280def _rule_computed(
281 root: Path, relative: Path, emitted: frozenset[str] | None
282) -> Provenance | None:
283 del emitted
284 return _computed(root, relative)
285
286
287def _rule_generated(
288 root: Path, relative: Path, emitted: frozenset[str] | None
289) -> Provenance | None:
290 prog = footman.prog()
291 generated = emitted_paths(root) if emitted is None else emitted
292 if relative.as_posix() not in generated:
293 return None
294 return Provenance(
295 "generated",
296 "the workshop emitters, from workshop.toml",
297 f"edit workshop.toml (or the emitters) and run `{prog} sync`",
298 )
299
300
301def _rule_composed(
302 root: Path, relative: Path, emitted: frozenset[str] | None
303) -> Provenance | None:
304 del emitted
305 from livery.workshop._fragment_engine import PACKAGE_PREFIX
306 from livery.workshop._packages import member_depth
307 from livery.workshop._shipped_files import shipped
308
309 fragments, _order = shipped(root)
310 # A package's file is composed from the `package/` fragments.
311 depth = member_depth(root, relative)
312 inner = PACKAGE_PREFIX + Path(*relative.parts[depth:]).as_posix() if depth else ""
313 owners = [
314 fragment.owner
315 for fragment in fragments
316 if fragment.target in (relative.as_posix(), inner)
317 ]
318 if not owners:
319 return None
320 prog = footman.prog()
321 return Provenance(
322 "composed",
323 f"the fragment engine, from {', '.join(dict.fromkeys(owners))}",
324 f"edit inside its regions, or the extension's lines, and run `{prog} sync`",
325 )
326
327
328def _rule_seed(
329 root: Path, relative: Path, emitted: frozenset[str] | None
330) -> Provenance | None:
331 del emitted
332 del root
333 from livery.workshop._seeds import PROJECT_SEEDS
334
335 if relative.as_posix() not in PROJECT_SEEDS:
336 return None
337 return Provenance(
338 "seed",
339 "written at birth from the extensions' seeds",
340 "yours: edit directly; nothing rewrites it",
341 )
342
343
344def _rule_receipts(
345 root: Path, relative: Path, emitted: frozenset[str] | None
346) -> Provenance | None:
347 del root, emitted
348 if relative.as_posix() != ".workshop-rendered":
349 return None
350 prog = footman.prog()
351 return Provenance(
352 "receipts",
353 "what the fragment engine last wrote into the workspace's files",
354 f"never by hand; `{prog} sync` keeps it",
355 )
356
357
358def _rule_contract(
359 root: Path, relative: Path, emitted: frozenset[str] | None
360) -> Provenance | None:
361 del root, emitted
362 if relative.name != "workshop.toml":
363 return None
364 return Provenance(
365 "contract",
366 "the workspace contract, config-as-code",
367 "edit directly and merge; governance applies itself on main",
368 )
369
370
371def _rule_environment(
372 root: Path, relative: Path, emitted: frozenset[str] | None
373) -> Provenance | None:
374 del root, emitted
375 if relative.as_posix() != ".repo.env":375 ↛ 377line 375 didn't jump to line 377 because the condition on line 375 was always true
376 return None
377 prog = footman.prog()
378 return Provenance(
379 "environment",
380 "the committed rung of the env cascade",
381 f"`{prog} env.set KEY --scope=repo`, or edit directly",
382 )
383
384
385def _rule_toolchain(
386 root: Path, relative: Path, emitted: frozenset[str] | None
387) -> Provenance | None:
388 del root, emitted
389 if relative.as_posix() != "uv.lock":
390 return None
391 return Provenance(
392 "toolchain",
393 "uv's lockfile",
394 "`uv lock` (or the update wave); never by hand",
395 )
396
397
398def _rule_member(
399 root: Path, relative: Path, emitted: frozenset[str] | None
400) -> Provenance | None:
401 """A package's own files: its changelog config, its receipts, its content."""
402 del emitted
403 from livery.workshop._packages import member_depth
404
405 depth = member_depth(root, relative)
406 if not depth:
407 return None
408 prog = footman.prog()
409 member = Path(*relative.parts[:depth])
410 rest = Path(*relative.parts[depth:]).as_posix()
411 if rest == ".workshop-rendered":
412 return Provenance(
413 "receipts",
414 "what the render wrote into this package for the steps' files",
415 f"never by hand; `{prog} sync` keeps it",
416 )
417 from livery.workshop._fragments import package_files
418
419 if rest in package_files():419 ↛ 420line 419 didn't jump to line 420 because the condition on line 419 was never true
420 return Provenance(
421 "rendered",
422 "a step record's fragment for this package's kind",
423 f"edit the record's fragment and run `{prog} sync`; a"
424 " deeper file with InheritParentConfig carries this package's own lines",
425 )
426 if "/content/" in rest:
427 return Provenance(
428 "extension content",
429 f"{member.as_posix()}: what this extension ships; the"
430 " provenance lint keeps its header",
431 f"edit directly here; `{prog} sync` delivers it",
432 )
433 return Provenance(
434 "yours",
435 f"{member.as_posix()}: the package's own file since its birth",
436 "edit directly",
437 )
438
439
440# The builtin ladder as ranked rules: an extension registers its own beside
441# them, at the rank that says where it stands.
442register_channels(
443 [
444 ChannelRule("materialised", _rule_materialised, 100, "livery.workshop"),
445 ChannelRule("computed", _rule_computed, 95, "livery.workshop"),
446 ChannelRule("generated", _rule_generated, 90, "livery.workshop"),
447 ChannelRule("composed", _rule_composed, 85, "livery.workshop"),
448 ChannelRule("seed", _rule_seed, 70, "livery.workshop"),
449 ChannelRule("receipts", _rule_receipts, 60, "livery.workshop"),
450 ChannelRule("contract", _rule_contract, 50, "livery.workshop"),
451 ChannelRule("environment", _rule_environment, 40, "livery.workshop"),
452 ChannelRule("toolchain", _rule_toolchain, 30, "livery.workshop"),
453 ChannelRule("member", _rule_member, 20, "livery.workshop"),
454 ]
455)
456
457
458def _tracked_paths() -> list[str]:
459 """Git-tracked paths, the completion surface for explain."""
460 root = workspace_root()
461 if root is None:
462 return []
463 try:
464 return git.ls_files(root)
465 except git.GitError:
466 return []
467
468
469@task
470def explain(
471 path: Annotated[
472 Arg[str],
473 ask(),
474 suggest(_tracked_paths, strict=False),
475 doc("the file to explain, relative to the workspace root, or a step's name"),
476 ] = "",
477) -> None:
478 """Name a file's owning channel, its source and its edit path; or what a step runs.
479
480 Every answer for a file has the same three lines; a file no channel
481 claims is yours, which is the honest default, not an error. A
482 step's name, ``typecheck.mypy``, prints the command the step runs
483 and what the engine appends to it.
484 """
485 if not path:
486 fail(f"name a file: `{footman.prog()} explain pyproject.toml`")
487 root = workspace_root()
488 if root is None:
489 fail("no workspace: no workshop.toml above the working directory")
490 from livery.workshop._steps import steps_by_name
491
492 record = steps_by_name().get(path)
493 if record is not None:
494 from livery.workshop._words import explained
495
496 for line in explained(record):
497 print(line)
498 return
499 raw = Path(path)
500 if raw.is_absolute():
501 try:
502 raw = raw.relative_to(root)
503 except ValueError:
504 fail(f"{path} is outside this workspace")
505 relative = Path(os.path.normpath(str(raw)))
506 if not relative.parts or relative.parts[0] == "..":
507 fail(f"{path} is outside this workspace")
508 for line in describe(root, relative):
509 print(line)
510
511
512def describe(root: Path, relative: Path) -> list[str]:
513 """The lines ``fm explain`` prints for *relative*: category, channel, claims.
514
515 A file is claimed by each step that reads it and each CI job whose
516 declared inputs read it, the job as ``<point>/<job>``. A contract
517 also names the schema it is judged by, with the owners whose keys
518 the schema holds.
519 """
520 from livery.workshop._packages import discover_packages
521 from livery.workshop._points import jobs_reading
522
523 packages = discover_packages(root) if (root / "packages").is_dir() else ()
524 unit, inside = unit_of(root, packages, relative.as_posix())
525 lines = [f" {relative.as_posix()}"]
526 if unit is not None:526 ↛ 529line 526 didn't jump to line 529 because the condition on line 526 was always true
527 category = category_of(unit, inside)
528 lines.append(f" category: {category.name} ({category.supplier})")
529 found = channel_of(root, relative)
530 answer = found.provenance if found is not None else classify(root, relative)
531 supplier = found.supplier if found is not None else "livery.workshop"
532 lines.append(f" channel: {answer.channel} ({supplier})")
533 lines.append(f" source: {answer.source}")
534 lines.append(f" edit: {answer.edit}")
535 from livery.workshop._steps import claimants
536
537 claims = list(claimants(unit, inside)) if unit is not None else []
538 claims.extend(jobs_reading(root, relative.as_posix()))
539 if claims:
540 lines.append(f" claimed by: {', '.join(claims)}")
541 from livery.workshop._schema import judged_by
542
543 schema = judged_by(root, relative)
544 if schema:
545 lines.append(f" {schema}")
546 lines.extend(f" {line}" for line in owned_lines(root, relative))
547 return lines
548
549
550def unit_of(
551 root: Path, packages: tuple[Package, ...], path: str
552) -> tuple[Package | None, str]:
553 """The package *path* belongs to and the path inside it, or the root's unit.
554
555 A path under no package is the workspace unit's, relative to the
556 root; None when the root has no unit to speak of.
557 """
558 from livery.workshop._packages import workspace_suite
559
560 for package in packages:
561 if path.startswith(package.path + "/"):
562 return package, path[len(package.path) + 1 :]
563 return workspace_suite(root) or _root_unit(root), path
564
565
566def _root_unit(root: Path) -> Package:
567 """The workspace unit for a root without its own tests directory."""
568 return Package(directory=root, path=".", name="workspace", depends=())
569
570
571def owned_lines(root: Path, relative: Path) -> list[str]:
572 """What a managed file carries that the repository owns, one line each.
573
574 A marked region is named with the lines its markers enclose. A file
575 without one says nothing.
576 """
577 from livery.workshop import _regions
578
579 path = root / relative
580 if not path.is_file():
581 return []
582 text = path.read_text(encoding="utf-8", errors="replace")
583 return [
584 f"region {region.name}: lines {region.first} to {region.last}, yours to"
585 " edit inside the markers; the render keeps it"
586 for region in _regions.regions_in(text)
587 ]
588
589
590def _content_trees(root: Path) -> list[tuple[str, Path]]:
591 """Each workspace package's shipped content tree, with its extension name."""
592 from livery.workshop._packages import package_directories
593
594 trees = []
595 for directory in package_directories(root):
596 src = directory / "src"
597 if not src.is_dir():597 ↛ 598line 597 didn't jump to line 598 because the condition on line 597 was never true
598 continue
599 for content in sorted(src.rglob("content")):
600 if not content.is_dir():600 ↛ 601line 600 didn't jump to line 601 because the condition on line 600 was never true
601 continue
602 if {"templates", "content"} & set(content.relative_to(src).parts[:-1]):602 ↛ 603line 602 didn't jump to line 603 because the condition on line 602 was never true
603 continue # a seed's own content tree, written at a birth
604 extension = ".".join(content.parent.relative_to(src).parts)
605 trees.append((extension, content))
606 return trees
607
608
609def content_lint(
610 root: Path, *, fix: bool = False, files: frozenset[str] | None = None
611) -> list[str]:
612 """Extension content files missing their computed header; ``fix`` writes it.
613
614 *files* keeps the lint to those root-relative files; None lints
615 every content file.
616
617 Only the workspace's own packages are linted: an installed
618 extension's content is its home repository's to keep. Files without
619 a comment syntax are exempt, and so are the fragment engine's
620 templates under `content/root/` and `content/package/`, and under
621 `content/for/<target>/root/` and `content/for/<target>/package/`,
622 whose composed files carry headers of their own, and the seeds under
623 `content/seeds/` and the templates' files under `content/templates/`,
624 which become the workspace's own files.
625 """
626 from livery.workshop._seeds import SEEDS, TEMPLATES
627 from livery.workshop._shipped_files import (
628 FOR_CONTENT,
629 PACKAGE_CONTENT,
630 ROOT_CONTENT,
631 )
632
633 problems = []
634 for extension, content in _content_trees(root):
635 for path in sorted(content.rglob("*")):
636 if not path.is_file() or "__pycache__" in path.parts:
637 continue
638 if files is not None and path.relative_to(root).as_posix() not in files:638 ↛ 639line 638 didn't jump to line 639 because the condition on line 638 was never true
639 continue
640 # A template the fragment engine composes into a workspace file
641 # carries that file's own header; this one would land in it.
642 parts = path.relative_to(content).parts
643 if parts[0] in (ROOT_CONTENT, PACKAGE_CONTENT, SEEDS, TEMPLATES):
644 continue
645 if (
646 parts[0] == FOR_CONTENT
647 and len(parts) > 3
648 and parts[2] in (ROOT_CONTENT, PACKAGE_CONTENT)
649 ):
650 continue
651 style = comment_style(path)
652 if not style:
653 continue
654 header = content_header(extension, style)
655 if has_header(path, header):
656 continue
657 if fix:
658 inject(path, header)
659 problems.append(f"{path.relative_to(root).as_posix()}: header written")
660 else:
661 problems.append(
662 f"{path.relative_to(root).as_posix()}: missing its header"
663 )
664 return problems
665
666
667@task(name="provenance")
668def provenance_check(
669 fix: Annotated[bool, doc("write the computed headers in place")] = False,
670) -> None:
671 """Check shipped extension content opens with its provenance header.
672
673 Part of the gate. Nobody composes a header by hand: ``--fix``
674 writes the computed text, and the render and emitters inject
675 theirs into everything they write.
676 """
677 check_content(fix=fix)
678
679
680def check_content(*, fix: bool = False, files: frozenset[str] | None = None) -> None:
681 """The provenance check over the content files in scope; refuses a missing header.
682
683 The engine behind `fm provenance` and the gate's ``provenance.check``: *files*
684 keeps it to those root-relative files, None to every content file.
685 """
686 root = workspace_root()
687 if root is None:687 ↛ 688line 687 didn't jump to line 688 because the condition on line 687 was never true
688 fail("no workspace: no workshop.toml above the working directory")
689 findings = content_lint(root, fix=fix, files=files)
690 for line in findings:
691 print(f" {line}")
692 if findings and not fix:
693 fail(
694 "extension content is missing provenance headers: run"
695 f" `{footman.prog()} check --fix` to write them"
696 )